@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/esm/modules/word/layout/layout-full.js

@@ -0,0 +1,1696 @@
+/**
+ * Full Layout Engine — produces a complete LayoutDocument with positioned elements.
+ *
+ * Uses the pagination result from layoutDocument() for page assignments,
+ * then computes precise positions (x, y, width, height) for every body
+ * element on each page.
+ *
+ * This is the bridge between the page-number-only LayoutResult and the
+ * fully positioned LayoutDocument that renderers (SVG, PDF, Canvas) can consume.
+ *
+ * Coverage: every variant of `BodyContent` from `../types` produces a
+ * `PageContent` variant in the output. The `default:` branch of the
+ * dispatch switch in `buildPage()` is a `never`-typed exhaustiveness
+ * guard — adding a new body variant without a matching layout function
+ * is a build error, never a silent drop.
+ */
+import { measureTextWidth, mapToStandardFont } from "../../../utils/font-metrics.js";
+import { ommlToMathML } from "../advanced/math-convert.js";
+import { extractMathText, isHyperlink, isRun } from "../core/text-utils.js";
+import { EMU_PER_POINT } from "../units.js";
+import { layoutDocument } from "./layout.js";
+import { DEFAULT_PAGE_HEIGHT_TWIPS, DEFAULT_PAGE_MARGIN_TWIPS, DEFAULT_PAGE_WIDTH_TWIPS } from "./layout-constants.js";
+/**
+ * Perform full document layout, producing a LayoutDocument with precise positions.
+ *
+ * @param doc - The parsed DOCX document.
+ * @param options - Layout and font options.
+ * @returns A fully positioned LayoutDocument.
+ */
+export function layoutDocumentFull(doc, options) {
+    // First pass: get page assignments via the existing lightweight layout
+    const layoutResult = layoutDocument(doc, options);
+    // Second pass: compute precise positions for each page. Footnote
+    // ids that don't fit on a given page are carried over to the next
+    // (a later page may still have room thanks to less body content
+    // or fewer of its own newly-introduced notes).
+    const pages = [];
+    const bodyPageCount = layoutResult.pageCount;
+    let pendingFootnoteIds = [];
+    for (let pageNum = 1; pageNum <= bodyPageCount; pageNum++) {
+        const result = buildPage(doc, pageNum, layoutResult, options, pendingFootnoteIds);
+        pages.push(result.page);
+        pendingFootnoteIds = result.deferredFootnoteIds;
+    }
+    // Defensive: if the last page still has deferred footnotes, append
+    // a synthetic page that hosts them. Without this, references would
+    // silently lose their content. This is rare (it only fires when an
+    // oversized footnote stack on the last body page didn't fit).
+    if (pendingFootnoteIds.length > 0 && bodyPageCount > 0) {
+        const overflowResult = buildPage(doc, bodyPageCount + 1, 
+        // Reuse the last page's `LayoutResult` shape: contentPages
+        // entries for already-placed body items still point at earlier
+        // pages, so the synthetic page won't pick up extra body
+        // content; only the carried footnote queue renders.
+        layoutResult, options, pendingFootnoteIds);
+        pages.push(overflowResult.page);
+    }
+    return {
+        pages,
+        totalPages: pages.length,
+        bookmarkPages: layoutResult.bookmarkPages,
+        sectionBreaks: computeSectionBreaks(layoutResult)
+    };
+}
+// =============================================================================
+// Internal: Page Building
+// =============================================================================
+const DEFAULT_FONT_SIZE_PT = 12;
+/**
+ * Compute the longest available horizontal slot on the line whose
+ * vertical span is `[lineY, lineY + lineHeight)`. Returns `xOffset`
+ * (relative to the content-area's left edge) and `width`. When no
+ * exclusion intersects the line the result is `{ xOffset: 0, width:
+ * contentWidth }` (full width).
+ *
+ * Algorithm:
+ *  1. Collect all exclusions whose y-band intersects the line.
+ *  2. For each, derive the "blocked" x-interval on the content axis
+ *     based on `wrapSide`:
+ *      - `bothSides` blocks `[xLeft, xRight]` only.
+ *      - `left` blocks `[xLeft, contentWidth]` (text wraps on the
+ *         float's left side only).
+ *      - `right` blocks `[0, xRight]`.
+ *      - `largest` picks whichever side of the float is wider; the
+ *         narrower side is blocked.
+ *  3. Subtract every blocked interval from `[0, contentWidth]` and
+ *     return the longest remaining gap.
+ */
+function availableSlotForLine(ctx, lineY, lineHeight) {
+    const lineBottom = lineY + lineHeight;
+    const blocked = [];
+    for (const ex of ctx.exclusions) {
+        // Strict overlap check: a line that just touches the float's
+        // bottom edge (`lineY === ex.yBottom`) does NOT need to wrap.
+        if (lineBottom <= ex.yTop || lineY >= ex.yBottom) {
+            continue;
+        }
+        const exLeft = Math.max(0, ex.xLeft);
+        const exRight = Math.min(ctx.contentWidth, ex.xRight);
+        if (exLeft >= exRight) {
+            continue;
+        }
+        switch (ex.wrapSide) {
+            case "bothSides":
+                blocked.push({ lo: exLeft, hi: exRight });
+                break;
+            case "left":
+                // Float blocks the right half of the line.
+                blocked.push({ lo: exLeft, hi: ctx.contentWidth });
+                break;
+            case "right":
+                blocked.push({ lo: 0, hi: exRight });
+                break;
+            case "largest": {
+                const leftSpace = exLeft;
+                const rightSpace = ctx.contentWidth - exRight;
+                if (rightSpace >= leftSpace) {
+                    // Wrap on the right (block to the left of the float).
+                    blocked.push({ lo: 0, hi: exRight });
+                }
+                else {
+                    blocked.push({ lo: exLeft, hi: ctx.contentWidth });
+                }
+                break;
+            }
+        }
+    }
+    if (blocked.length === 0) {
+        return { xOffset: 0, width: ctx.contentWidth };
+    }
+    // Merge overlapping blocked intervals.
+    blocked.sort((a, b) => a.lo - b.lo);
+    const merged = [];
+    for (const seg of blocked) {
+        const last = merged[merged.length - 1];
+        if (last && seg.lo <= last.hi) {
+            last.hi = Math.max(last.hi, seg.hi);
+        }
+        else {
+            merged.push({ lo: seg.lo, hi: seg.hi });
+        }
+    }
+    // Build available gaps in [0, contentWidth] minus the merged blocks.
+    const gaps = [];
+    let cursor = 0;
+    for (const seg of merged) {
+        if (seg.lo > cursor) {
+            gaps.push({ x: cursor, width: seg.lo - cursor });
+        }
+        cursor = Math.max(cursor, seg.hi);
+    }
+    if (cursor < ctx.contentWidth) {
+        gaps.push({ x: cursor, width: ctx.contentWidth - cursor });
+    }
+    if (gaps.length === 0) {
+        // Line entirely blocked. Fall back to full content width to avoid
+        // pathological zero-width wraps that would loop forever; the line
+        // visually overlaps the float (fail-safe behaviour).
+        return { xOffset: 0, width: ctx.contentWidth };
+    }
+    // Pick the widest gap.
+    let best = gaps[0];
+    for (let i = 1; i < gaps.length; i++) {
+        if (gaps[i].width > best.width) {
+            best = gaps[i];
+        }
+    }
+    return { xOffset: best.x, width: best.width };
+}
+function twipsToPt(twips) {
+    return twips / 20;
+}
+function buildPage(doc, pageNumber, layout, options, pendingFootnoteIds) {
+    const sectionProps = doc.sectionProperties;
+    const geometry = computePageGeometry(sectionProps, options?.pageGeometry);
+    const content = [];
+    const imageMap = buildImageMap(doc.images);
+    /**
+     * Footnote ids referenced from the raw `BodyContent` items assigned
+     * to this page, collected as we iterate so the order is the
+     * document-reading order. Pending ids carried over from the
+     * previous page are queued ahead so they render before this page's
+     * own newly-introduced notes.
+     */
+    const footnoteRefIds = [...pendingFootnoteIds];
+    /**
+     * Wrap exclusion zones from floats with `square` / `tight` /
+     * `through` wrap, populated as we iterate so subsequent paragraphs
+     * (later in document order) avoid them line-by-line. Floats that
+     * appear AFTER a paragraph in the source do not push back into
+     * preceding lines — this matches Word's behaviour where re-flow on
+     * insertion happens at edit time, not render time.
+     */
+    const pageExclusions = [];
+    let cursorY = 0; // relative to content area top
+    for (let i = 0; i < doc.body.length; i++) {
+        if (layout.contentPages[i] !== pageNumber) {
+            continue;
+        }
+        const item = doc.body[i];
+        collectFootnoteRefsFromBody(item, footnoteRefIds);
+        const pageContext = {
+            exclusions: pageExclusions,
+            contentWidth: geometry.contentWidth
+        };
+        switch (item.type) {
+            case "paragraph": {
+                const laid = layoutParagraph(item, cursorY, geometry.contentWidth, options, pageContext, imageMap);
+                content.push({ ...laid, sourceIndex: i });
+                cursorY = laid.rect.y + laid.rect.height;
+                break;
+            }
+            case "table": {
+                const laid = layoutTable(item, cursorY, geometry.contentWidth, i, options, imageMap);
+                content.push(laid);
+                cursorY = laid.rect.y + laid.rect.height;
+                break;
+            }
+            case "floatingImage": {
+                const laid = layoutFloatingImage(item, cursorY, geometry.contentWidth, geometry.contentHeight, geometry, i, imageMap);
+                content.push(laid);
+                // Cursor advancement strategy:
+                //  - `wrap.style === "topAndBottom"` (or no wrap and not
+                //    behindDoc) forces body content to clear the float
+                //    vertically; advance the cursor to the float's bottom edge
+                //    plus the wrap.bottom margin.
+                //  - `square` / `tight` / `through` register an exclusion zone
+                //    so subsequent paragraph wrap avoids the float laterally;
+                //    the body cursor is NOT advanced (text wraps around).
+                //  - Behind-document floats never displace text.
+                //  - Inline-like floats (no anchor, no behindDoc) keep the
+                //    backwards-compatible advance behaviour.
+                const hasAnchor = item.simplePos != null ||
+                    item.horizontalPosition != null ||
+                    item.verticalPosition != null;
+                const wrapStyle = item.wrap?.style;
+                const isWrapAround = wrapStyle === "square" || wrapStyle === "tight" || wrapStyle === "through";
+                const advanceCursor = (!hasAnchor && !item.behindDoc && !isWrapAround) || wrapStyle === "topAndBottom";
+                if (advanceCursor) {
+                    const padBottom = item.wrap?.margins?.bottom ? emuToPt(item.wrap.margins.bottom) : 0;
+                    cursorY = laid.rect.y + laid.rect.height + padBottom;
+                }
+                if (isWrapAround && !item.behindDoc) {
+                    // Add an exclusion band covering the float's rect plus its
+                    // wrap padding margins. Subsequent paragraphs (later in doc
+                    // order) will wrap their lines around this rectangle.
+                    const padL = laid.wrap?.margins?.left ?? 0;
+                    const padR = laid.wrap?.margins?.right ?? 0;
+                    const padT = laid.wrap?.margins?.top ?? 0;
+                    const padB = laid.wrap?.margins?.bottom ?? 0;
+                    pageExclusions.push({
+                        xLeft: laid.rect.x - padL,
+                        xRight: laid.rect.x + laid.rect.width + padR,
+                        yTop: laid.rect.y - padT,
+                        yBottom: laid.rect.y + laid.rect.height + padB,
+                        wrapSide: laid.wrap?.side ?? "bothSides"
+                    });
+                }
+                break;
+            }
+            case "textBox": {
+                const laid = layoutTextBox(item, cursorY, geometry.contentWidth, i, options, imageMap);
+                content.push(laid);
+                cursorY = laid.rect.y + laid.rect.height;
+                break;
+            }
+            case "drawingShape": {
+                const laid = layoutDrawingShape(item, cursorY, geometry.contentWidth, i, options, imageMap);
+                content.push(laid);
+                cursorY = laid.rect.y + laid.rect.height;
+                break;
+            }
+            case "chart":
+            case "chartEx": {
+                const laid = layoutChart(item, cursorY, geometry.contentWidth, i);
+                content.push(laid);
+                cursorY = laid.rect.y + laid.rect.height;
+                break;
+            }
+            case "sdt": {
+                const laid = layoutSdt(item, cursorY, geometry.contentWidth, i, options, imageMap);
+                content.push(laid);
+                cursorY = laid.rect.y + laid.rect.height;
+                break;
+            }
+            case "math": {
+                const laid = layoutMath(item, cursorY, geometry.contentWidth, i, options);
+                content.push(laid);
+                cursorY = laid.rect.y + laid.rect.height;
+                break;
+            }
+            case "checkBox": {
+                const laid = layoutCheckBox(item, cursorY, i, options);
+                content.push(laid);
+                cursorY = laid.rect.y + laid.rect.height;
+                break;
+            }
+            case "tableOfContents": {
+                const laid = layoutTableOfContents(item, cursorY, geometry.contentWidth, i, options, imageMap);
+                content.push(laid);
+                cursorY = laid.rect.y + laid.rect.height;
+                break;
+            }
+            case "altChunk": {
+                const laid = layoutAltChunk(item, cursorY, geometry.contentWidth, i);
+                content.push(laid);
+                cursorY = laid.rect.y + laid.rect.height;
+                break;
+            }
+            case "opaqueDrawing": {
+                const laid = layoutOpaqueDrawing(item, cursorY, geometry.contentWidth, i);
+                content.push(laid);
+                cursorY = laid.rect.y + laid.rect.height;
+                break;
+            }
+            default: {
+                // Compile-time exhaustiveness check. Adding a new variant to
+                // `BodyContent` triggers a TypeScript error here until a
+                // corresponding case + layout function are added above. This
+                // replaces the previous "Skip unsupported types" silent drop.
+                const _exhaustive = item;
+                throw new Error(`layoutDocumentFull: unhandled BodyContent variant ${_exhaustive.type}`);
+            }
+        }
+    }
+    const header = layoutHeader(doc, pageNumber, geometry, options, imageMap);
+    const footer = layoutFooter(doc, pageNumber, geometry, options, imageMap);
+    // Compute the absolute (page-y) lower edge of body content so the
+    // footnote layout knows how much vertical room is actually free.
+    // `cursorY` is content-area-relative; convert by adding `marginTop`.
+    const bodyBottomPageY = geometry.marginTop + cursorY;
+    const footnoteResult = layoutFootnotes(doc, footnoteRefIds, geometry, options, bodyBottomPageY, imageMap);
+    // Decide whether the visual separator above the footnote area is the
+    // standard "separator" or the wider "continuationSeparator".
+    // A continuation page is one whose footnote area is *entirely*
+    // composed of notes deferred from a previous page (no body item on
+    // this page introduces a new reference). Detect by comparing the
+    // footnote-id sequence against the supplied `pendingFootnoteIds`.
+    let footnoteSeparator;
+    if (footnoteResult.laid.length > 0) {
+        const introducedHere = footnoteRefIds.length > pendingFootnoteIds.length;
+        const sepKind = introducedHere
+            ? "separator"
+            : "continuationSeparator";
+        // Place the rule a few points above the first footnote paragraph.
+        const stackTop = footnoteResult.laid[0].rect.y;
+        footnoteSeparator = { y: stackTop - 4, kind: sepKind };
+    }
+    return {
+        page: {
+            pageNumber,
+            geometry,
+            content,
+            ...(header.length > 0 ? { header } : {}),
+            ...(footer.length > 0 ? { footer } : {}),
+            ...(footnoteResult.laid.length > 0 ? { footnoteArea: footnoteResult.laid } : {}),
+            ...(footnoteSeparator ? { footnoteSeparator } : {})
+        },
+        deferredFootnoteIds: footnoteResult.deferred
+    };
+}
+function layoutFootnotes(doc, ids, geometry, options, bodyBottomPageY, imageMap) {
+    if (ids.length === 0 || !doc.footnotes || doc.footnotes.length === 0) {
+        return { laid: [], deferred: [] };
+    }
+    const noteById = new Map();
+    for (const note of doc.footnotes) {
+        const kind = note.type ?? "normal";
+        if (kind === "normal") {
+            noteById.set(note.id, note);
+        }
+    }
+    const footerOffsetPt = geometry.height - twipsToPt(doc.sectionProperties?.margins?.footer ?? 720);
+    /**
+     * Vertical room available for the footnote stack on this page.
+     * The stack must sit between `bodyBottomPageY` (top) and
+     * `footerOffsetPt` (bottom); anything that doesn't fit gets
+     * deferred. A small minimum is enforced so a page that's almost
+     * full still flushes at least one footnote (the alternative —
+     * deferring everything indefinitely — would loop forever in
+     * pathological inputs).
+     */
+    const availableSpace = Math.max(0, footerOffsetPt - bodyBottomPageY);
+    const seen = new Set();
+    const laidPerNote = [];
+    const heightPerNote = [];
+    const idsLaid = [];
+    for (const id of ids) {
+        if (seen.has(id)) {
+            continue;
+        }
+        seen.add(id);
+        const note = noteById.get(id);
+        if (!note) {
+            continue;
+        }
+        const note_paragraphs = [];
+        let cursor = 0;
+        for (const para of note.content) {
+            if (para.type !== "paragraph") {
+                continue;
+            }
+            const p = layoutParagraph(para, cursor, geometry.contentWidth, options, undefined, imageMap);
+            note_paragraphs.push(p);
+            cursor = p.rect.y + p.rect.height;
+        }
+        laidPerNote.push(note_paragraphs);
+        heightPerNote.push(cursor);
+        idsLaid.push(id);
+    }
+    // Greedily fit notes into the available space. The first note is
+    // always laid out — even if it overflows — so a page that
+    // references a single oversized note still renders something
+    // (avoids losing data); the renderer will visually clip into the
+    // bottom margin in that pathological case.
+    const fitNotes = [];
+    const fitHeights = [];
+    const deferred = [];
+    let stackHeight = 0;
+    for (let i = 0; i < idsLaid.length; i++) {
+        const noteHeight = heightPerNote[i];
+        const wouldBe = stackHeight + noteHeight;
+        const fitsCleanly = wouldBe <= availableSpace;
+        const isFirstAndForced = fitNotes.length === 0;
+        if (fitsCleanly || isFirstAndForced) {
+            fitNotes.push(laidPerNote[i]);
+            fitHeights.push(noteHeight);
+            stackHeight = wouldBe;
+        }
+        else {
+            deferred.push(idsLaid[i]);
+        }
+    }
+    if (fitNotes.length === 0) {
+        return { laid: [], deferred };
+    }
+    // Translate the whole stack so its bottom edge is at footerOffsetPt.
+    const top = footerOffsetPt - stackHeight;
+    const flat = [];
+    let runningOffset = top;
+    for (let i = 0; i < fitNotes.length; i++) {
+        for (const p of fitNotes[i]) {
+            flat.push({
+                ...p,
+                rect: { ...p.rect, y: p.rect.y + runningOffset }
+            });
+        }
+        runningOffset += fitHeights[i];
+    }
+    return { laid: flat, deferred };
+}
+/**
+ * Walk a `BodyContent` item's run-level descendants and append every
+ * `FootnoteRefContent` id to `out`, in document order. Recurses into
+ * the few container variants whose children embed paragraphs (textBox,
+ * drawingShape, sdt, tableOfContents, table cells).
+ */
+function collectFootnoteRefsFromBody(item, out) {
+    switch (item.type) {
+        case "paragraph":
+            collectFootnoteRefsFromParagraph(item, out);
+            return;
+        case "table":
+            for (const r of item.rows) {
+                for (const c of r.cells) {
+                    for (const inner of c.content) {
+                        collectFootnoteRefsFromBody(inner, out);
+                    }
+                }
+            }
+            return;
+        case "textBox":
+            for (const child of item.content) {
+                collectFootnoteRefsFromBody(child, out);
+            }
+            return;
+        case "drawingShape":
+            if (item.textContent) {
+                for (const child of item.textContent) {
+                    collectFootnoteRefsFromBody(child, out);
+                }
+            }
+            return;
+        case "sdt":
+            for (const child of item.content) {
+                if (child && typeof child === "object" && "type" in child) {
+                    collectFootnoteRefsFromBody(child, out);
+                }
+            }
+            return;
+        case "tableOfContents":
+            if (item.cachedParagraphs) {
+                for (const para of item.cachedParagraphs) {
+                    collectFootnoteRefsFromBody(para, out);
+                }
+            }
+            return;
+        case "floatingImage":
+        case "math":
+        case "checkBox":
+        case "chart":
+        case "chartEx":
+        case "altChunk":
+        case "opaqueDrawing":
+            return;
+        default: {
+            const _exhaustive = item;
+            void _exhaustive;
+        }
+    }
+}
+function collectFootnoteRefsFromParagraph(para, out) {
+    for (const child of para.children) {
+        if ("type" in child && child.type === "hyperlink") {
+            collectFootnoteRefsFromHyperlink(child, out);
+        }
+        else if (!("type" in child) || child.type === undefined) {
+            // Plain Run (no `type` discriminator).
+            collectFootnoteRefsFromRun(child, out);
+        }
+        else if (child.type === "insertedRun" ||
+            child.type === "deletedRun" ||
+            child.type === "movedFromRun" ||
+            child.type === "movedToRun") {
+            // Tracked-change wrappers carry a single `run` (singular) per
+            // ECMA-376 — see `InsertedRun.run`, `DeletedRun.run`, etc.
+            collectFootnoteRefsFromRun(child.run, out);
+        }
+        // BookmarkStart / BookmarkEnd / Comment* / MoveRangeMarker /
+        // CustomXmlTrackingMarker carry no runnable text — nothing to
+        // collect.
+    }
+}
+function collectFootnoteRefsFromHyperlink(link, out) {
+    for (const child of link.children) {
+        if (!("type" in child) || child.type === undefined) {
+            collectFootnoteRefsFromRun(child, out);
+        }
+    }
+}
+function collectFootnoteRefsFromRun(run, out) {
+    if (!run || !Array.isArray(run.content)) {
+        return;
+    }
+    for (const c of run.content) {
+        if (c.type === "footnoteRef") {
+            out.push(c.id);
+        }
+    }
+}
+/**
+ * Resolve which header reference to use for a given page within a
+ * section, per ECMA-376 §17.10:
+ *
+ *  - `titlePage === true` and `pageNumber === 1` → the `"first"` reference
+ *  - `evenAndOddHeaders === true` (settings) and even page number → `"even"`
+ *  - otherwise → the `"default"` reference
+ *
+ * Each rule falls back to `"default"` (then to the first available ref)
+ * if its preferred type isn't declared in the section's references.
+ */
+function pickHeaderFooterRef(refs, pageNumber, titlePage, evenAndOdd) {
+    const find = (t) => refs.find(r => r.type === t);
+    if (titlePage && pageNumber === 1) {
+        const first = find("first");
+        if (first) {
+            return first;
+        }
+    }
+    if (evenAndOdd && pageNumber % 2 === 0) {
+        const even = find("even");
+        if (even) {
+            return even;
+        }
+    }
+    return find("default") ?? refs[0];
+}
+/**
+ * Lay out the paragraphs and tables of the resolved header for a page.
+ *
+ * Resolution order: first/even/default per `pickHeaderFooterRef`.
+ * The header band's local y-axis starts at the section's
+ * `pgMar.header` (in pt) below the page top, mirroring Word's
+ * "Header from top" setting; renderers consume the resulting layout-y
+ * directly as a page-y offset.
+ *
+ * Tables in header content are laid out with the same `layoutTable`
+ * that body content uses, and surfaced via the union type on
+ * `LayoutPage.header` so renderers can pick them up alongside
+ * paragraphs without a special path.
+ */
+function layoutHeader(doc, pageNumber, geometry, options, imageMap) {
+    const refs = doc.sectionProperties?.headers;
+    if (!refs || refs.length === 0) {
+        return [];
+    }
+    const titlePage = doc.sectionProperties?.titlePage === true;
+    const evenAndOdd = doc.settings?.evenAndOddHeaders === true;
+    const ref = pickHeaderFooterRef(refs, pageNumber, titlePage, evenAndOdd);
+    if (!ref) {
+        return [];
+    }
+    const part = doc.headers?.get(ref.rId);
+    if (!part) {
+        return [];
+    }
+    const headerOffsetPt = twipsToPt(doc.sectionProperties?.margins?.header ?? 720);
+    return layoutHeaderFooterChildren(part.content.children, headerOffsetPt, geometry, options, imageMap);
+}
+function layoutFooter(doc, pageNumber, geometry, options, imageMap) {
+    const refs = doc.sectionProperties?.footers;
+    if (!refs || refs.length === 0) {
+        return [];
+    }
+    const titlePage = doc.sectionProperties?.titlePage === true;
+    const evenAndOdd = doc.settings?.evenAndOddHeaders === true;
+    const ref = pickHeaderFooterRef(refs, pageNumber, titlePage, evenAndOdd);
+    if (!ref) {
+        return [];
+    }
+    const part = doc.footers?.get(ref.rId);
+    if (!part) {
+        return [];
+    }
+    // Footer band starts at `pageHeight - pgMar.footer` so layout-y is
+    // already a page-absolute coordinate (matching the header path,
+    // where `pgMar.header` is the absolute offset of the band from the
+    // page top). Renderers consume both bands with the same
+    // "treat layout-y as page-y" rule.
+    const footerOffsetPt = geometry.height - twipsToPt(doc.sectionProperties?.margins?.footer ?? 720);
+    return layoutHeaderFooterChildren(part.content.children, footerOffsetPt, geometry, options, imageMap);
+}
+function layoutHeaderFooterChildren(children, initialCursorY, geometry, options, imageMap) {
+    const out = [];
+    let cursor = initialCursorY;
+    for (let idx = 0; idx < children.length; idx++) {
+        const child = children[idx];
+        if (child.type === "paragraph") {
+            const laid = layoutParagraph(child, cursor, geometry.contentWidth, options, undefined, imageMap);
+            out.push(laid);
+            cursor = laid.rect.y + laid.rect.height;
+        }
+        else if (child.type === "table") {
+            const laid = layoutTable(child, cursor, geometry.contentWidth, idx, options, imageMap);
+            out.push(laid);
+            cursor = laid.rect.y + laid.rect.height;
+        }
+    }
+    return out;
+}
+function computePageGeometry(sectionProps, override) {
+    const widthTwips = sectionProps?.pageSize?.width ?? DEFAULT_PAGE_WIDTH_TWIPS;
+    const heightTwips = sectionProps?.pageSize?.height ?? DEFAULT_PAGE_HEIGHT_TWIPS;
+    const sectionWidth = twipsToPt(widthTwips);
+    const sectionHeight = twipsToPt(heightTwips);
+    const sectionMarginTop = twipsToPt(sectionProps?.margins?.top ?? DEFAULT_PAGE_MARGIN_TWIPS);
+    const sectionMarginBottom = twipsToPt(sectionProps?.margins?.bottom ?? DEFAULT_PAGE_MARGIN_TWIPS);
+    const sectionMarginLeft = twipsToPt(sectionProps?.margins?.left ?? DEFAULT_PAGE_MARGIN_TWIPS);
+    const sectionMarginRight = twipsToPt(sectionProps?.margins?.right ?? DEFAULT_PAGE_MARGIN_TWIPS);
+    // Per-axis override: callers (PDF bridge, custom hosts) may want to
+    // pin the page size or margin on one axis without disturbing the
+    // others — `pageWidth` doesn't imply overriding margins, etc.
+    const width = override?.pageWidth ?? sectionWidth;
+    const height = override?.pageHeight ?? sectionHeight;
+    const marginTop = override?.marginTop ?? sectionMarginTop;
+    const marginBottom = override?.marginBottom ?? sectionMarginBottom;
+    const marginLeft = override?.marginLeft ?? sectionMarginLeft;
+    const marginRight = override?.marginRight ?? sectionMarginRight;
+    return {
+        width,
+        height,
+        marginTop,
+        marginBottom,
+        marginLeft,
+        marginRight,
+        contentWidth: width - marginLeft - marginRight,
+        contentHeight: height - marginTop - marginBottom
+    };
+}
+function computeSectionBreaks(layout) {
+    const breaks = [0]; // First section starts at page 0
+    let prevSection = 0;
+    for (let i = 0; i < layout.contentPages.length; i++) {
+        const section = layout.contentSections[i];
+        if (section > prevSection) {
+            breaks.push(layout.contentPages[i] - 1);
+            prevSection = section;
+        }
+    }
+    return breaks;
+}
+// =============================================================================
+// Internal: Paragraph Layout
+// =============================================================================
+function layoutParagraph(para, startY, contentWidth, options, pageContext, imageMap) {
+    const props = para.properties;
+    const spacing = props?.spacing;
+    const headingScale = getHeadingFontScale(getHeadingLevel(props));
+    // Space before
+    let spaceBefore = 0;
+    if (spacing?.beforeAutoSpacing) {
+        spaceBefore = 5;
+    }
+    else if (spacing?.before != null) {
+        spaceBefore = twipsToPt(spacing.before);
+    }
+    const indent = props?.indent;
+    const leftIndentPt = indent?.left ? twipsToPt(indent.left) : 0;
+    const firstLineIndentPt = indent?.firstLine ? twipsToPt(indent.firstLine) : 0;
+    const alignment = props?.alignment ?? "left";
+    // Line height
+    let lineHeightPt = DEFAULT_FONT_SIZE_PT * 1.2;
+    if (spacing?.line) {
+        const rule = spacing.lineRule ?? "auto";
+        switch (rule) {
+            case "exact":
+                lineHeightPt = twipsToPt(spacing.line);
+                break;
+            case "atLeast":
+                lineHeightPt = Math.max(twipsToPt(spacing.line), lineHeightPt);
+                break;
+            case "auto":
+                lineHeightPt = DEFAULT_FONT_SIZE_PT * 1.2 * (spacing.line / 240);
+                break;
+        }
+    }
+    lineHeightPt *= headingScale;
+    // Collect runs
+    const segments = collectParagraphSegments(para);
+    const fullAvailableWidth = contentWidth - leftIndentPt;
+    // When a page has wrap exclusions (square / tight / through floats)
+    // we wrap line-by-line, asking the page context for the widest free
+    // slot at the line's actual y-position. Otherwise we use the
+    // legacy single-width path which never re-evaluates width across
+    // lines — this preserves the existing layout output for documents
+    // with no wrap (the overwhelming majority).
+    let lines;
+    let perLineSlots;
+    if (pageContext && pageContext.exclusions.length > 0) {
+        const result = wrapSegmentsToLinesWithExclusions(segments, leftIndentPt, firstLineIndentPt, headingScale, lineHeightPt, startY + spaceBefore, pageContext);
+        lines = result.lines;
+        perLineSlots = result.slots;
+    }
+    else {
+        lines = wrapSegmentsToLines(segments, fullAvailableWidth, firstLineIndentPt, headingScale);
+    }
+    // Build line boxes
+    const lineBoxes = [];
+    let yOffset = spaceBefore;
+    for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+        const lineSegments = lines[lineIdx];
+        const runs = [];
+        // Resolve the line's effective slot. With exclusions each line has
+        // its own usable [xOffset, width]; otherwise we keep the legacy
+        // single-width behaviour and place the first line indent.
+        const slot = perLineSlots?.[lineIdx] ?? {
+            xOffset: 0,
+            width: fullAvailableWidth
+        };
+        const lineLeftIndent = perLineSlots ? slot.xOffset : leftIndentPt;
+        const lineAvailableWidth = perLineSlots ? slot.width : fullAvailableWidth;
+        let xPos = lineIdx === 0 ? firstLineIndentPt : 0;
+        // Calculate line width for alignment, and find the tallest item
+        // so the line's height accommodates inline images.
+        let lineWidth = 0;
+        let lineMaxHeight = lineHeightPt;
+        for (const seg of lineSegments) {
+            if ("type" in seg && seg.type === "image") {
+                const w = emuToPt(seg.content.width);
+                const h = emuToPt(seg.content.height);
+                lineWidth += w;
+                if (h > lineMaxHeight) {
+                    lineMaxHeight = h;
+                }
+            }
+            else {
+                const fontSize = getRunFontSizePt(seg.properties) * headingScale;
+                const fontName = mapToStandardFont(resolveRunFontName(seg.properties));
+                lineWidth += measureTextWidth(seg.text, fontName, fontSize);
+            }
+        }
+        // Apply alignment
+        if (alignment === "center") {
+            xPos = (lineAvailableWidth - lineWidth) / 2;
+        }
+        else if (alignment === "right" || alignment === "end") {
+            xPos = lineAvailableWidth - lineWidth;
+        }
+        xPos += lineLeftIndent;
+        for (const seg of lineSegments) {
+            if ("type" in seg && seg.type === "image") {
+                const widthPt = emuToPt(seg.content.width);
+                const heightPt = emuToPt(seg.content.height);
+                const img = seg.content.rId ? imageMap?.get(seg.content.rId) : undefined;
+                runs.push({
+                    type: "image",
+                    x: xPos,
+                    width: widthPt,
+                    height: heightPt,
+                    data: img?.data ?? new Uint8Array(0),
+                    mimeType: mediaTypeToMime(img?.mediaType),
+                    altText: seg.content.altText
+                });
+                xPos += widthPt;
+                continue;
+            }
+            const fontSize = getRunFontSizePt(seg.properties) * headingScale;
+            const fontName = resolveRunFontName(seg.properties);
+            const measuredFont = mapToStandardFont(fontName);
+            const segWidth = measureTextWidth(seg.text, measuredFont, fontSize);
+            runs.push({
+                text: seg.text,
+                x: xPos,
+                width: segWidth,
+                font: fontName,
+                fontSize,
+                bold: seg.properties?.bold || undefined,
+                italic: seg.properties?.italic || undefined,
+                color: resolveColorHex(seg.properties?.color),
+                underline: seg.properties?.underline !== undefined ? true : undefined,
+                strikethrough: seg.properties?.strike || undefined,
+                verticalAlign: seg.properties?.vertAlign === "superscript" || seg.properties?.vertAlign === "subscript"
+                    ? seg.properties.vertAlign
+                    : undefined
+            });
+            xPos += segWidth;
+        }
+        const mappedAlignment = alignment === "both"
+            ? "justify"
+            : alignment === "end"
+                ? "right"
+                : alignment === "start"
+                    ? "left"
+                    : alignment;
+        lineBoxes.push({
+            y: yOffset,
+            height: lineMaxHeight,
+            // Baseline for text sits at 80% of line height; for an
+            // image-dominant line this puts the image's bottom near the
+            // baseline, matching Word's default inline-image alignment.
+            baseline: lineMaxHeight * 0.8,
+            runs,
+            alignment: mappedAlignment
+        });
+        yOffset += lineMaxHeight;
+    }
+    // If empty paragraph, still advance by one line
+    if (lineBoxes.length === 0) {
+        yOffset += lineHeightPt;
+    }
+    // Space after
+    let spaceAfter = 0;
+    if (spacing?.afterAutoSpacing) {
+        spaceAfter = 5;
+    }
+    else if (spacing?.after != null) {
+        spaceAfter = twipsToPt(spacing.after);
+    }
+    const totalHeight = yOffset + spaceAfter;
+    return {
+        type: "paragraph",
+        rect: { x: 0, y: startY, width: contentWidth, height: totalHeight },
+        lines: lineBoxes,
+        sourceIndex: 0 // overwritten by caller
+    };
+}
+// =============================================================================
+// Internal: Table Layout
+// =============================================================================
+function layoutTable(table, startY, contentWidth, sourceIndex, options, imageMap) {
+    const numCols = table.rows.length > 0 ? table.rows[0].cells.length : 0;
+    const colWidth = numCols > 0 ? contentWidth / numCols : contentWidth;
+    const cells = [];
+    let cursorY = 0;
+    for (let ri = 0; ri < table.rows.length; ri++) {
+        const row = table.rows[ri];
+        let maxRowHeight = DEFAULT_FONT_SIZE_PT * 1.5; // minimum row height
+        for (let ci = 0; ci < row.cells.length; ci++) {
+            const cell = row.cells[ci];
+            const cellX = ci * colWidth;
+            const cellContent = [];
+            let cellCursorY = 2; // cell padding top
+            for (const block of cell.content) {
+                if (block.type === "paragraph") {
+                    const laid = layoutParagraph(block, cellCursorY, colWidth - 4, options, undefined, imageMap);
+                    cellContent.push({ ...laid, sourceIndex: -1 });
+                    cellCursorY = laid.rect.y + laid.rect.height;
+                }
+                // nested tables skipped for simplicity
+            }
+            const cellHeight = cellCursorY + 2; // cell padding bottom
+            if (cellHeight > maxRowHeight) {
+                maxRowHeight = cellHeight;
+            }
+            cells.push({
+                rect: { x: cellX, y: startY + cursorY, width: colWidth, height: cellHeight },
+                row: ri,
+                col: ci,
+                content: cellContent
+            });
+        }
+        // Normalize cell heights to row max
+        for (const c of cells) {
+            if (c.row === ri) {
+                c.rect.height = maxRowHeight;
+            }
+        }
+        cursorY += maxRowHeight;
+    }
+    return {
+        type: "table",
+        rect: { x: 0, y: startY, width: contentWidth, height: cursorY },
+        cells,
+        sourceIndex
+    };
+}
+/**
+ * Walk a paragraph's children and emit a flat sequence of paragraph
+ * segments — text runs preserve their formatting; inline images become
+ * dedicated `ImageSegment` tokens so the wrap engine treats them as
+ * unbreakable atoms positioned in document order. Hyperlinks are
+ * descended into; bookmark / comment / track-change wrappers are
+ * ignored for layout purposes.
+ */
+function collectParagraphSegments(para) {
+    const segments = [];
+    for (const child of para.children) {
+        if (isRun(child)) {
+            pushRunSegments(child, segments);
+        }
+        else if (isHyperlink(child)) {
+            for (const run of child.children) {
+                pushRunSegments(run, segments);
+            }
+        }
+    }
+    return segments;
+}
+/**
+ * Emit `ParagraphSegment` tokens for a single run, preserving the
+ * relative order of text fragments and inline images. Consecutive
+ * text-bearing entries are coalesced into one `TextSegment` so the
+ * wrap engine sees fewer atoms.
+ */
+function pushRunSegments(run, out) {
+    let pending = "";
+    for (const item of run.content) {
+        if (item.type === "text") {
+            pending += item.text;
+        }
+        else if (item.type === "tab") {
+            pending += "    ";
+        }
+        else if (item.type === "break") {
+            pending += "\n";
+        }
+        else if (item.type === "image") {
+            if (pending.length > 0) {
+                out.push({ text: pending, properties: run.properties });
+                pending = "";
+            }
+            out.push({ type: "image", content: item, properties: run.properties });
+        }
+    }
+    if (pending.length > 0) {
+        out.push({ text: pending, properties: run.properties });
+    }
+}
+/**
+ * Wrap a paragraph's text segments into lines whose available widths
+ * vary based on per-line wrap exclusions (square / tight / through
+ * floats). Word-level break points only — character-level shaping is
+ * out of scope for the layout engine.
+ *
+ * Returns both the per-line `TextSegment[]` and a parallel array of
+ * `{ xOffset, width }` describing where each line is placed within
+ * the content area. Callers use the slot to set per-line indent /
+ * available width for alignment.
+ */
+function wrapSegmentsToLinesWithExclusions(segments, leftIndentPt, firstLineIndentPt, headingScale, lineHeightPt, paragraphTopPageY, pageContext) {
+    const atoms = [];
+    for (const seg of segments) {
+        if ("type" in seg && seg.type === "image") {
+            atoms.push({
+                width: emuToPt(seg.content.width),
+                isSpace: false,
+                isImage: true,
+                properties: seg.properties,
+                imageContent: seg.content
+            });
+            continue;
+        }
+        const fontSize = getRunFontSizePt(seg.properties) * headingScale;
+        const fontName = mapToStandardFont(resolveRunFontName(seg.properties));
+        // Split on runs of whitespace, keeping the whitespace tokens so
+        // wrapping can decide whether to drop trailing space at line end.
+        const tokens = seg.text.split(/(\s+)/);
+        for (const tok of tokens) {
+            if (tok.length === 0) {
+                continue;
+            }
+            atoms.push({
+                text: tok,
+                width: measureTextWidth(tok, fontName, fontSize),
+                properties: seg.properties,
+                isSpace: /^\s+$/.test(tok),
+                isImage: false
+            });
+        }
+    }
+    const lines = [];
+    const slots = [];
+    if (atoms.length === 0) {
+        return { lines, slots };
+    }
+    let cursorAtom = 0;
+    let lineIdx = 0;
+    while (cursorAtom < atoms.length) {
+        const lineY = paragraphTopPageY + lineIdx * lineHeightPt;
+        const slot = availableSlotForLine(pageContext, lineY, lineHeightPt);
+        // The first line of a paragraph may carry an extra `firstLineIndent`
+        // (from `<w:ind firstLine="…"/>`) which subtracts from the usable
+        // width on that line only. Subsequent lines use the full slot width
+        // (offset by the paragraph's `leftIndentPt`, which is applied by
+        // the caller's run x-positioning logic, not here).
+        const indentForThisLine = lineIdx === 0 ? firstLineIndentPt : 0;
+        let usable = slot.width - indentForThisLine;
+        let lineXOffset = slot.xOffset + indentForThisLine;
+        // Also subtract the paragraph's own leftIndentPt (which the legacy
+        // path applies through `availableWidth = contentWidth -
+        // leftIndentPt`). We mirror that here so wrap behaviour matches
+        // when no exclusion is in play.
+        if (slot.xOffset === 0 && leftIndentPt > 0) {
+            usable -= leftIndentPt;
+            lineXOffset += leftIndentPt;
+        }
+        if (usable <= 0) {
+            // Pathological — the line is fully blocked or narrower than the
+            // first-line indent. Skip the y position by advancing one line
+            // height; placing zero-content lines indefinitely is worse than
+            // leaving a small visual gap.
+            lines.push([]);
+            slots.push({ xOffset: lineXOffset, width: Math.max(0, usable) });
+            lineIdx++;
+            // Re-evaluate without retrying same atoms (no progress -> bail
+            // after a sane number of retries to avoid infinite loops on a
+            // degenerate page).
+            if (lineIdx > 1000) {
+                break;
+            }
+            continue;
+        }
+        // Greedily pack atoms into the line until the next atom would
+        // overflow `usable`. A leading whitespace atom on a fresh line is
+        // dropped (matches typical text engines).
+        if (atoms[cursorAtom].isSpace) {
+            cursorAtom++;
+            if (cursorAtom >= atoms.length) {
+                break;
+            }
+        }
+        const lineAtoms = [];
+        let lineWidth = 0;
+        while (cursorAtom < atoms.length) {
+            const atom = atoms[cursorAtom];
+            const next = lineWidth + atom.width;
+            if (next > usable && lineAtoms.length > 0) {
+                // Atom would overflow; commit the line and go to next.
+                break;
+            }
+            lineAtoms.push(atom);
+            lineWidth = next;
+            cursorAtom++;
+        }
+        // Trim trailing whitespace so alignment computation is correct.
+        // Don't trim trailing image atoms (they're not whitespace).
+        while (lineAtoms.length > 0 && lineAtoms[lineAtoms.length - 1].isSpace) {
+            const drop = lineAtoms.pop();
+            lineWidth -= drop.width;
+        }
+        // Reassemble the line into `ParagraphSegment[]`. Adjacent text
+        // atoms with identical properties merge; image atoms remain
+        // standalone.
+        const merged = [];
+        for (const atom of lineAtoms) {
+            if (atom.isImage) {
+                merged.push({
+                    type: "image",
+                    content: atom.imageContent,
+                    properties: atom.properties
+                });
+                continue;
+            }
+            const last = merged[merged.length - 1];
+            const lastIsText = last && !("type" in last);
+            if (lastIsText && last.properties === atom.properties) {
+                merged[merged.length - 1] = {
+                    text: last.text + atom.text,
+                    properties: atom.properties
+                };
+            }
+            else {
+                merged.push({ text: atom.text, properties: atom.properties });
+            }
+        }
+        lines.push(merged);
+        slots.push({ xOffset: lineXOffset, width: usable });
+        lineIdx++;
+        if (lineIdx > 100000) {
+            // Defensive — degenerate inputs shouldn't loop the engine.
+            break;
+        }
+    }
+    return { lines, slots };
+}
+function wrapSegmentsToLines(segments, availableWidth, firstLineIndent, headingScale) {
+    const lines = [];
+    let currentLine = [];
+    let currentLineWidth = 0;
+    let isFirstLine = true;
+    let effectiveWidth = availableWidth - firstLineIndent;
+    const flushLine = () => {
+        lines.push(currentLine);
+        currentLine = [];
+        currentLineWidth = 0;
+        if (isFirstLine) {
+            isFirstLine = false;
+            effectiveWidth = availableWidth;
+        }
+    };
+    for (const segment of segments) {
+        if ("type" in segment && segment.type === "image") {
+            // Inline images are unbreakable atoms.  Width comes from the
+            // source EMU; if the image alone exceeds the line we still
+            // place it (avoids losing content) — the renderer will overflow
+            // visually on that line, matching Word's behaviour for
+            // oversized inline images.
+            const imageWidth = emuToPt(segment.content.width);
+            const fitsCurrent = currentLineWidth + imageWidth <= effectiveWidth || currentLine.length === 0;
+            if (!fitsCurrent) {
+                flushLine();
+            }
+            currentLine.push(segment);
+            currentLineWidth += imageWidth;
+            continue;
+        }
+        const text = segment.text;
+        const fontSize = getRunFontSizePt(segment.properties) * headingScale;
+        const fontName = mapToStandardFont(resolveRunFontName(segment.properties));
+        const segmentWidth = measureTextWidth(text, fontName, fontSize);
+        if (currentLineWidth + segmentWidth <= effectiveWidth || currentLine.length === 0) {
+            currentLine.push(segment);
+            currentLineWidth += segmentWidth;
+        }
+        else {
+            // Word-level splitting
+            const words = text.split(/(\s+)/);
+            let bufferedText = "";
+            let bufferedWidth = 0;
+            for (const word of words) {
+                const wordWidth = measureTextWidth(word, fontName, fontSize);
+                if (currentLineWidth + bufferedWidth + wordWidth <= effectiveWidth ||
+                    (currentLine.length === 0 && bufferedText.length === 0)) {
+                    bufferedText += word;
+                    bufferedWidth += wordWidth;
+                }
+                else {
+                    if (bufferedText.length > 0) {
+                        currentLine.push({ text: bufferedText, properties: segment.properties });
+                    }
+                    flushLine();
+                    bufferedText = word;
+                    bufferedWidth = wordWidth;
+                }
+            }
+            if (bufferedText.length > 0) {
+                currentLine.push({ text: bufferedText, properties: segment.properties });
+                currentLineWidth += bufferedWidth;
+            }
+        }
+    }
+    if (currentLine.length > 0) {
+        lines.push(currentLine);
+    }
+    if (lines.length === 0 && segments.length > 0) {
+        lines.push(segments);
+    }
+    return lines;
+}
+function getHeadingLevel(props) {
+    if (!props) {
+        return 0;
+    }
+    if (props.outlineLevel !== undefined && props.outlineLevel >= 0 && props.outlineLevel <= 5) {
+        return props.outlineLevel + 1;
+    }
+    if (props.style) {
+        const match = /^[Hh]eading\s*(\d)$/i.exec(props.style);
+        if (match) {
+            return parseInt(match[1], 10);
+        }
+    }
+    return 0;
+}
+function getHeadingFontScale(level) {
+    switch (level) {
+        case 1:
+            return 2.0;
+        case 2:
+            return 1.5;
+        case 3:
+            return 1.17;
+        case 4:
+            return 1.0;
+        case 5:
+            return 0.83;
+        case 6:
+            return 0.67;
+        default:
+            return 1.0;
+    }
+}
+/**
+ * Resolve the effective font size in points for a run.
+ *
+ * `<w:sz w:val="…"/>` is in half-points; we halve.
+ *
+ * Sub/superscript runs are conventionally rendered at ~65 % of the
+ * surrounding text's size with a vertical baseline shift. The size
+ * scaling lives here so every measurement (line width, line height,
+ * wrap) sees the same value; the y-shift is applied at render time
+ * via `PositionedRun.verticalAlign`.
+ */
+function getRunFontSizePt(props) {
+    const base = props?.size ? props.size / 2 : DEFAULT_FONT_SIZE_PT;
+    if (props?.vertAlign === "superscript" || props?.vertAlign === "subscript") {
+        return base * 0.65;
+    }
+    return base;
+}
+function resolveRunFontName(props) {
+    if (!props?.font) {
+        return "Calibri";
+    }
+    if (typeof props.font === "string") {
+        return props.font;
+    }
+    return props.font.ascii ?? "Calibri";
+}
+function resolveColorHex(color) {
+    if (!color) {
+        return undefined;
+    }
+    if (typeof color === "string") {
+        return color;
+    }
+    if (typeof color === "object" && color !== null && "value" in color) {
+        return color.value;
+    }
+    return undefined;
+}
+// =============================================================================
+// Internal: Image / Geometry Helpers
+// =============================================================================
+function emuToPt(emu) {
+    return emu / EMU_PER_POINT;
+}
+/**
+ * Convert the docx-internal `ImageMediaType` (`"png"`, `"jpeg"`, …)
+ * to the standard MIME string consumers expect on
+ * `LayoutImage.mimeType` / `PositionedInlineImage.mimeType`. Unknown
+ * tags fall back to `application/octet-stream` so renderers can
+ * decide whether to skip or draw a placeholder.
+ */
+function mediaTypeToMime(mt) {
+    switch (mt) {
+        case "png":
+            return "image/png";
+        case "jpeg":
+            return "image/jpeg";
+        case "gif":
+            return "image/gif";
+        case "bmp":
+            return "image/bmp";
+        case "tiff":
+            return "image/tiff";
+        case "svg":
+            return "image/svg+xml";
+        case "webp":
+            return "image/webp";
+        case "emf":
+            return "image/x-emf";
+        case "wmf":
+            return "image/x-wmf";
+        default:
+            return "application/octet-stream";
+    }
+}
+function buildImageMap(images) {
+    const map = new Map();
+    if (!images) {
+        return map;
+    }
+    for (const img of images) {
+        if (img.rId) {
+            map.set(img.rId, img);
+        }
+        // Some images carry additional rIds (header/footer parts use their own
+        // local id space). Index by every known rId so layout can resolve
+        // either flavour.
+        if (Array.isArray(img.altRIds)) {
+            for (const aux of img.altRIds) {
+                map.set(aux, img);
+            }
+        }
+    }
+    return map;
+}
+// =============================================================================
+// Internal: FloatingImage / TextBox / Shape / Chart / SDT / Math / CheckBox
+// =============================================================================
+/**
+ * Resolve the page-content-area position of a floating image per
+ * ECMA-376 §20.4.2.10. Layout coordinates have origin at the top-left
+ * of the **content area**; floating-image anchors are normally
+ * expressed against the **page** or **margin**, so we translate
+ * accordingly.
+ *
+ * Resolution order:
+ *  1. `simplePos="1"` (we currently see only `simplePos.x`/`simplePos.y`
+ *     in the model; we treat its presence as the simplePos override)
+ *     — page-absolute EMU.
+ *  2. `horizontalPosition` / `verticalPosition` with `align` keywords
+ *     (left/center/right/inside/outside, top/center/bottom).
+ *  3. `horizontalPosition` / `verticalPosition` with `offset` (EMU)
+ *     relative to the chosen `relativeTo` reference.
+ *  4. Fall back to the cursor (inline-like behaviour).
+ *
+ * `relativeTo` reference points (subset we resolve):
+ *  - `"page"` — page top-left corner
+ *  - `"margin"` — margin box top-left corner (same as content area
+ *    origin in our coordinate system)
+ *  - `"column"` / `"character"` / `"paragraph"` etc. — fall back to the
+ *    cursor; reproducing them faithfully would require column/text-flow
+ *    info we don't keep at this stage.
+ */
+function resolveFloatingImageRect(fi, cursorY, contentWidth, contentHeight, geometry, widthPt, heightPt) {
+    const usingSimplePos = fi.simplePos !== undefined;
+    // 1. simplePos: page-absolute. Translate into content-area coords by
+    //    subtracting the page margins.
+    if (usingSimplePos) {
+        const pageX = emuToPt(fi.simplePos.x ?? 0);
+        const pageY = emuToPt(fi.simplePos.y ?? 0);
+        return {
+            x: pageX - geometry.marginLeft,
+            y: pageY - geometry.marginTop
+        };
+    }
+    // 2/3. positionH / positionV
+    const xPt = resolveHorizontal(fi, contentWidth, geometry, widthPt) ?? 0;
+    const yPt = resolveVertical(fi, cursorY, contentHeight, geometry, heightPt) ?? cursorY;
+    return { x: xPt, y: yPt };
+}
+function resolveHorizontal(fi, contentWidth, geometry, widthPt) {
+    const h = fi.horizontalPosition;
+    if (!h) {
+        return undefined;
+    }
+    const relTo = h.relativeTo ?? "column";
+    // Reference origin (in content-area coordinates) and width to anchor against.
+    let originX = 0;
+    let refWidth = contentWidth;
+    if (relTo === "page") {
+        originX = -geometry.marginLeft;
+        refWidth = geometry.width;
+    }
+    else if (relTo === "margin" || relTo === "leftMargin" || relTo === "rightMargin") {
+        originX = 0;
+        refWidth = contentWidth;
+    } // else: column/character/insideMargin/outsideMargin — fall back to content area
+    if (h.align) {
+        switch (h.align) {
+            case "left":
+            case "inside":
+                return originX;
+            case "right":
+            case "outside":
+                return originX + refWidth - widthPt;
+            case "center":
+                return originX + (refWidth - widthPt) / 2;
+        }
+    }
+    if (h.offset != null) {
+        return originX + emuToPt(h.offset);
+    }
+    return undefined;
+}
+function resolveVertical(fi, cursorY, contentHeight, geometry, heightPt) {
+    const v = fi.verticalPosition;
+    if (!v) {
+        return undefined;
+    }
+    const relTo = v.relativeTo ?? "paragraph";
+    let originY = cursorY;
+    let refHeight = contentHeight;
+    if (relTo === "page") {
+        originY = -geometry.marginTop;
+        refHeight = geometry.height;
+    }
+    else if (relTo === "margin" || relTo === "topMargin" || relTo === "bottomMargin") {
+        originY = 0;
+        refHeight = contentHeight;
+    } // else paragraph/line/text-anchored — keep cursor as origin
+    if (v.align) {
+        switch (v.align) {
+            case "top":
+            case "inside":
+                return originY;
+            case "bottom":
+            case "outside":
+                return originY + refHeight - heightPt;
+            case "center":
+                return originY + (refHeight - heightPt) / 2;
+        }
+    }
+    if (v.offset != null) {
+        return originY + emuToPt(v.offset);
+    }
+    return undefined;
+}
+function layoutFloatingImage(fi, cursorY, contentWidth, contentHeight, geometry, sourceIndex, imageMap) {
+    const widthPt = emuToPt(fi.width);
+    const heightPt = emuToPt(fi.height);
+    const { x: xPt, y: yPt } = resolveFloatingImageRect(fi, cursorY, contentWidth, contentHeight, geometry, widthPt, heightPt);
+    const img = fi.rId ? imageMap.get(fi.rId) : undefined;
+    const imageContent = img
+        ? {
+            type: "image",
+            rect: { x: xPt, y: yPt, width: widthPt, height: heightPt },
+            data: img.data,
+            mimeType: mediaTypeToMime(img.mediaType),
+            altText: fi.altText,
+            sourceIndex
+        }
+        : {
+            type: "image",
+            rect: { x: xPt, y: yPt, width: widthPt, height: heightPt },
+            data: new Uint8Array(0),
+            mimeType: "application/octet-stream",
+            altText: fi.altText,
+            sourceIndex
+        };
+    return {
+        type: "float",
+        rect: { x: xPt, y: yPt, width: widthPt, height: heightPt },
+        content: imageContent,
+        behindText: fi.behindDoc === true,
+        ...(fi.wrap ? { wrap: convertWrap(fi.wrap) } : {}),
+        sourceIndex
+    };
+}
+/**
+ * Translate the source `FloatingImage.wrap` (with `WrapMargins` in EMU)
+ * into the layout-side `LayoutFloatWrap` (with margins already in
+ * points so renderers don't need to know about EMU).
+ */
+function convertWrap(wrap) {
+    const out = {
+        style: wrap.style
+    };
+    if (wrap.side) {
+        out.side = wrap.side;
+    }
+    if (wrap.margins) {
+        const m = {};
+        if (wrap.margins.top != null) {
+            m.top = emuToPt(wrap.margins.top);
+        }
+        if (wrap.margins.bottom != null) {
+            m.bottom = emuToPt(wrap.margins.bottom);
+        }
+        if (wrap.margins.left != null) {
+            m.left = emuToPt(wrap.margins.left);
+        }
+        if (wrap.margins.right != null) {
+            m.right = emuToPt(wrap.margins.right);
+        }
+        if (Object.keys(m).length > 0) {
+            out.margins = m;
+        }
+    }
+    return out;
+}
+function layoutTextBox(tb, startY, contentWidth, sourceIndex, options, imageMap) {
+    const widthPt = tb.width != null ? twipsToPt(tb.width) : contentWidth;
+    // Lay out inner paragraphs against the text-box width; their positions
+    // are returned relative to the box's top-left so renderers translate
+    // by `rect.x`/`rect.y`.
+    const inner = [];
+    let innerCursor = 0;
+    for (const child of tb.content) {
+        const laid = layoutParagraph(child, innerCursor, widthPt, options, undefined, imageMap);
+        inner.push({ ...laid, sourceIndex });
+        innerCursor = laid.rect.y + laid.rect.height;
+    }
+    const heightPt = tb.height != null ? twipsToPt(tb.height) : Math.max(innerCursor, 12);
+    return {
+        type: "textBox",
+        rect: { x: 0, y: startY, width: widthPt, height: heightPt },
+        content: inner,
+        border: tb.stroke && tb.strokeColor
+            ? { width: 0.75, color: normaliseHex(tb.strokeColor) }
+            : undefined,
+        background: tb.fill && tb.fillColor ? normaliseHex(tb.fillColor) : undefined,
+        sourceIndex
+    };
+}
+function layoutDrawingShape(shape, startY, contentWidth, sourceIndex, options, imageMap) {
+    const widthPt = emuToPt(shape.width);
+    const heightPt = emuToPt(shape.height);
+    const innerWidth = Math.min(widthPt, contentWidth);
+    const innerContent = [];
+    if (shape.textContent && shape.textContent.length > 0) {
+        let cursor = 0;
+        for (const para of shape.textContent) {
+            const laid = layoutParagraph(para, cursor, innerWidth, options, undefined, imageMap);
+            innerContent.push({ ...laid, sourceIndex });
+            cursor = laid.rect.y + laid.rect.height;
+        }
+    }
+    return {
+        type: "shape",
+        rect: { x: 0, y: startY, width: widthPt, height: heightPt },
+        preset: shape.shapeType,
+        fillColor: shape.noFill ? undefined : normaliseHexOrUndefined(shape.fillColor),
+        strokeColor: shape.noOutline ? undefined : normaliseHexOrUndefined(shape.outlineColor),
+        strokeWidth: shape.outlineWidth != null ? emuToPt(shape.outlineWidth) : undefined,
+        textContent: innerContent.length > 0 ? innerContent : undefined,
+        sourceIndex
+    };
+}
+function layoutChart(ch, startY, contentWidth, sourceIndex) {
+    // Source dimensions:
+    //  - ChartContent stores width/height inside the inner Chart model
+    //    (writer emits `<wp:extent>` from `chart.width/height`; reader
+    //    populates them from the original drawing's `<wp:extent>`).
+    //  - ChartExContent carries width/height directly on the content.
+    // Both fall back to a 6"×3.5" default that matches Microsoft Word's
+    // default insert size when the source supplied none.
+    const widthEmu = ch.type === "chart" ? (ch.chart?.width ?? 5486400) : (ch.width ?? 5486400);
+    const heightEmu = ch.type === "chart" ? (ch.chart?.height ?? 3200400) : (ch.height ?? 3200400);
+    const widthPt = Math.min(emuToPt(widthEmu), contentWidth);
+    const heightPt = emuToPt(heightEmu);
+    const title = ch.type === "chart" ? (ch.chart?.title ?? ch.name) : ch.name;
+    return {
+        type: "chart",
+        rect: { x: 0, y: startY, width: widthPt, height: heightPt },
+        chartKind: ch.type === "chart" ? "chart" : "chartEx",
+        title,
+        altText: ch.altText,
+        source: ch,
+        sourceIndex
+    };
+}
+function layoutSdt(sdt, startY, contentWidth, sourceIndex, options, imageMap) {
+    // SDT is a transparent flow container in layout terms: lay out its
+    // children inline and report a rect that encloses them. Inline-only
+    // children (bare runs) are skipped — the SDT-as-block contract is
+    // what layout cares about.
+    const inner = [];
+    let cursor = 0;
+    for (const child of sdt.content) {
+        if ("type" in child) {
+            if (child.type === "paragraph") {
+                const laid = layoutParagraph(child, cursor, contentWidth, options, undefined, imageMap);
+                inner.push({ ...laid, sourceIndex });
+                cursor = laid.rect.y + laid.rect.height;
+            }
+            else if (child.type === "table") {
+                const laid = layoutTable(child, cursor, contentWidth, sourceIndex, options, imageMap);
+                inner.push(laid);
+                cursor = laid.rect.y + laid.rect.height;
+            }
+            // Run-only SDT children are not flowed at the block level.
+        }
+    }
+    return {
+        type: "sdt",
+        rect: { x: 0, y: startY, width: contentWidth, height: cursor },
+        content: inner,
+        tag: sdt.properties?.tag,
+        alias: sdt.properties?.alias,
+        sourceIndex
+    };
+}
+function layoutMath(mb, startY, contentWidth, sourceIndex, options) {
+    const text = extractMathText(mb.content);
+    let mathML;
+    try {
+        mathML = ommlToMathML(mb.content);
+    }
+    catch {
+        mathML = undefined;
+    }
+    const fontSize = DEFAULT_FONT_SIZE_PT;
+    const lineHeight = fontSize * 1.2;
+    // Width is approximated from the plain-text fallback so renderers that
+    // don't handle MathML still see a reasonable bounding box.
+    const fontName = mapToStandardFont(options?.fonts?.get("Cambria Math") ?? "Cambria Math");
+    const widthPt = Math.min(measureTextWidth(text, fontName, fontSize), contentWidth);
+    return {
+        type: "math",
+        rect: { x: 0, y: startY, width: widthPt, height: lineHeight },
+        text,
+        mathML,
+        sourceIndex
+    };
+}
+function layoutCheckBox(cb, startY, sourceIndex, options) {
+    const fontSize = DEFAULT_FONT_SIZE_PT;
+    const checked = cb.checked === true;
+    const glyph = checked
+        ? (cb.checkedState?.value ?? "\u2611") // ☑
+        : (cb.uncheckedState?.value ?? "\u2610"); // ☐
+    const fontName = mapToStandardFont(cb.checkedState?.font ?? options?.fonts?.get("MS Gothic") ?? "MS Gothic");
+    const widthPt = measureTextWidth(glyph, fontName, fontSize);
+    return {
+        type: "checkBox",
+        rect: { x: 0, y: startY, width: widthPt, height: fontSize * 1.2 },
+        checked,
+        glyph,
+        fontSize,
+        sourceIndex
+    };
+}
+function layoutTableOfContents(toc, startY, contentWidth, sourceIndex, options, imageMap) {
+    const entries = [];
+    let cursor = 0;
+    if (toc.cachedParagraphs && toc.cachedParagraphs.length > 0) {
+        for (const para of toc.cachedParagraphs) {
+            const laid = layoutParagraph(para, cursor, contentWidth, options, undefined, imageMap);
+            entries.push({ ...laid, sourceIndex });
+            cursor = laid.rect.y + laid.rect.height;
+        }
+    }
+    else {
+        // Stub: emit a single placeholder paragraph so renderers always have
+        // something to render. Consumers wanting a real TOC should run
+        // `updateTableOfContents()` before layout.
+        const stub = {
+            type: "paragraph",
+            children: [{ content: [{ type: "text", text: "[Table of Contents]" }] }]
+        };
+        const laid = layoutParagraph(stub, 0, contentWidth, options, undefined, imageMap);
+        entries.push({ ...laid, sourceIndex });
+        cursor = laid.rect.height;
+    }
+    return {
+        type: "tableOfContents",
+        rect: { x: 0, y: startY, width: contentWidth, height: cursor },
+        entries,
+        sourceIndex
+    };
+}
+function layoutAltChunk(ac, startY, contentWidth, sourceIndex) {
+    // Layout cannot interpret HTML / RTF / MHT payloads; reserve a
+    // placeholder rect proportional to a small fixed height so renderers
+    // can show a substitution glyph or run their own foreign-content
+    // pipeline.
+    const heightPt = DEFAULT_FONT_SIZE_PT * 3;
+    return {
+        type: "altChunk",
+        rect: { x: 0, y: startY, width: contentWidth, height: heightPt },
+        contentType: ac.contentType ?? "application/octet-stream",
+        fileName: ac.fileName,
+        sourceIndex
+    };
+}
+function layoutOpaqueDrawing(od, startY, contentWidth, sourceIndex) {
+    // We have no idea how big the drawing is from XML alone; reserve a
+    // square-ish placeholder roughly matching a typical chart slot. High-
+    // fidelity renderers can re-parse `rawXml` if they need exact size.
+    const heightPt = DEFAULT_FONT_SIZE_PT * 12;
+    return {
+        type: "opaqueDrawing",
+        rect: { x: 0, y: startY, width: contentWidth, height: heightPt },
+        rawXml: od.rawXml,
+        sourceIndex
+    };
+}
+function normaliseHex(hex) {
+    return hex.startsWith("#") ? hex.slice(1) : hex;
+}
+function normaliseHexOrUndefined(hex) {
+    return hex ? normaliseHex(hex) : undefined;
+}