@rowsncolumns/toolkit 24.4.1 → 24.4.3

package/dist/esm/exporter/xlsx/xlsx-export.js

@@ -3,16 +3,18 @@ import { zipSync } from "fflate";
 import { omitInvalidDataValidationError } from "../invalid-data-validation";
 import { buildAutoFilterConditionXml } from "../../autofilter-condition";
 import { applyPowerQueryParts } from "./power-query-builder";
+import { encodeImplicitIntersection } from "../../helpers/implicit-intersection";
 import { qualifyFutureFunctions } from "./future-functions";
 import { PERSON_CONTENT_TYPE, PERSON_REL_TYPE, PersonRegistry, THREADED_COMMENT_REL_TYPE, THREADED_COMMENTS_CONTENT_TYPE, ThreadedCommentsCollector, } from "./threaded-comments-builder";
 import { CFBEncryptor } from "../../excel-parser/cfb-encryptor";
 import { columnPixelToChars, imageUrlToBase64 } from "../../helpers";
+import { buildPrintAreaFormula, buildPrintTitlesFormula, isBuiltinPrintName, isHeaderFooterEmpty, PRINT_AREA_NAME, PRINT_TITLES_NAME, } from "../../print-settings";
 import { generateThemeXml } from "../../helpers/theme-xml-generator";
 import theme1Xml from "../../theme1";
 import { tokenize as defaultTokenizer } from "@rowsncolumns/calculator";
 import { CellXfsRegistry, deriveEffectiveNumberFormatFromFormula, } from "@rowsncolumns/spreadsheet-state";
 import { buildChartXml } from "./chart-builder";
-import { buildPivotCacheDefinitionXml, buildPivotTableRelsXml, buildPivotTableXml, } from "./pivot-builder";
+import { buildPivotCacheDefinitionXml, buildPivotTableRelsXml, buildPivotTableXml, calculatedFieldReferences, } from "./pivot-builder";
 import { buildSlicerCacheXml, buildSlicerXml } from "./slicer-builder";
 import { buildSparklineGroupsXml } from "./sparkline-builder";
 import { StyleBuilder } from "./style-builder";
@@ -21,7 +23,7 @@ const isStyleReference = (value) => !!value && typeof value === "object" && "sid
 const DEFAULT_COLUMN_WIDTH_PX = 100;
 const DEFAULT_ROW_HEIGHT_PX = 21;
 const pixelToPoints = (px) => Math.max(1, Number(((px * 72) / 96).toFixed(2)));
-export const createExcelFile = async ({ conditionalFormats: _conditionalFormats, dataValidations: _dataValidations, sheets, sheetData, sharedStrings: sourceSharedStrings, tables: _tables = [], cellXfs, theme, defaultFont, embeds = [], charts = [], slicers = [], pivotTables = [], externalLinks = [], namedRanges = [], namedCellStyles, customTableStyles, iterativeCalculationOptions, ignoreFormulaPatterns, citations, comments, password, locale, use1904 = false, properties, powerQuery, }) => {
+export const createExcelFile = async ({ conditionalFormats: _conditionalFormats, dataValidations: _dataValidations, sheets, sheetData, sharedStrings: sourceSharedStrings, tables: _tables = [], cellXfs, theme, defaultFont, embeds = [], charts = [], slicers = [], pivotTables = [], externalLinks = [], namedRanges = [], protectedRanges = [], namedCellStyles, customTableStyles, iterativeCalculationOptions, ignoreFormulaPatterns, citations, comments, password, locale, use1904 = false, properties, powerQuery, }) => {
     const sortedSheets = sortSheetsByIndex(sheets, true);
     const sharedStrings = new SharedStrings();
     // Workbook-scoped author registry shared across every sheet's threaded
@@ -183,12 +185,26 @@ export const createExcelFile = async ({ conditionalFormats: _conditionalFormats,
                 fieldIndex.set(name, fieldNameList.length);
                 fieldNameList.push(name);
             };
+            const calculatedNames = new Set((pivot.calculatedFields ?? []).map((c) => c.name));
             for (const r of pivot.rows ?? [])
                 registerField(r.field);
             for (const c of pivot.columns ?? [])
                 registerField(c.field);
-            for (const v of pivot.values ?? [])
-                registerField(v.field);
+            for (const v of pivot.values ?? []) {
+                if (!calculatedNames.has(v.field))
+                    registerField(v.field);
+            }
+            // Source fields a calculated field reads must exist in the cache
+            // for Excel to evaluate the formula; the calculated fields
+            // themselves come last, as Excel orders them.
+            for (const c of pivot.calculatedFields ?? []) {
+                for (const ref of calculatedFieldReferences(c.formula)) {
+                    if (!calculatedNames.has(ref))
+                        registerField(ref);
+                }
+            }
+            for (const c of pivot.calculatedFields ?? [])
+                registerField(c.name);
             const cacheXml = buildPivotCacheDefinitionXml(pivot, sourceSheetName, fieldNameList);
             const tableXml = buildPivotTableXml(pivot, cacheIndex, fieldIndex);
             if (!cacheXml || !tableXml)
@@ -233,6 +249,7 @@ export const createExcelFile = async ({ conditionalFormats: _conditionalFormats,
             sheetData,
             sheets: sortedSheets,
             locale,
+            protectedRanges,
         });
         return {
             index,
@@ -643,7 +660,7 @@ const getRowsForSheet = (sheetData, sheetId) => {
         sheetData[Number(sheetId)] ??
         []);
 };
-const buildWorksheetXml = ({ sheet, rows, sharedStrings, sourceSharedStrings, cellXfs, styleBuilder, tables, relationships, drawingContext, conditionalFormats, dataValidationsById, dataValidations, ignoreFormulaPatterns, citations, comments, personRegistry, slicerRelIds, sheetData, sheets, locale, }) => {
+const buildWorksheetXml = ({ sheet, rows, sharedStrings, sourceSharedStrings, cellXfs, styleBuilder, tables, relationships, drawingContext, conditionalFormats, dataValidationsById, dataValidations, ignoreFormulaPatterns, citations, comments, personRegistry, slicerRelIds, sheetData, sheets, locale, protectedRanges, }) => {
     const tableNameMap = buildTableNameMap(tables);
     const bounds = {
         minRow: Number.POSITIVE_INFINITY,
@@ -813,7 +830,8 @@ const buildWorksheetXml = ({ sheet, rows, sharedStrings, sourceSharedStrings, ce
         legacyDrawingXml = `<legacyDrawing r:id="${legacyDrawingRelId}"/>`;
     }
     const sheetDataXml = `<sheetData>${rowXmlChunks.join("")}</sheetData>`;
-    const pageMargins = DEFAULT_PAGE_MARGINS;
+    const protectionXml = buildSheetProtectionXml(sheet, protectedRanges);
+    const printSettingsXml = buildPrintSettingsXml(sheet.printSettings);
     // Build row data map for sparkline detection
     const rowDataMap = {};
     for (let rowIndex = 1; rowIndex < maxRows; rowIndex++) {
@@ -847,7 +865,7 @@ const buildWorksheetXml = ({ sheet, rows, sharedStrings, sourceSharedStrings, ce
         explicitDefaultColumnWidthPx > 0) {
         sheetFormatPrAttrs.push(`defaultColWidth="${columnPixelToChars(explicitDefaultColumnWidthPx).toFixed(2)}"`);
     }
-    const worksheetXml = `${XML_DECLARATION}<worksheet xmlns="${WORKSHEET_NS}" xmlns:r="${REL_NS}">${sheetPrXml}<dimension ref="${dimension}"/>${sheetViews}<sheetFormatPr ${sheetFormatPrAttrs.join(" ")}/>${columnXml}${sheetDataXml}${basicFilterXml}${mergeXml}${conditionalFormattingXml}${dataValidationsXml}${hyperlinksXml}${pageMargins}${drawingXml}${legacyDrawingXml}${tablePartsXml}${extLstXml}</worksheet>`;
+    const worksheetXml = `${XML_DECLARATION}<worksheet xmlns="${WORKSHEET_NS}" xmlns:r="${REL_NS}">${sheetPrXml}<dimension ref="${dimension}"/>${sheetViews}<sheetFormatPr ${sheetFormatPrAttrs.join(" ")}/>${columnXml}${sheetDataXml}${protectionXml}${basicFilterXml}${mergeXml}${conditionalFormattingXml}${dataValidationsXml}${hyperlinksXml}${printSettingsXml}${drawingXml}${legacyDrawingXml}${tablePartsXml}${extLstXml}</worksheet>`;
     return {
         xml: worksheetXml,
         relationshipsXml: relationships.toXml(),
@@ -1814,7 +1832,9 @@ function rewriteStructuredReferenceFormula(formula, tableNameMap, tables, rowNum
 }
 function sanitizeFormulaText(formula) {
     const normalized = sanitizeXmlText(formula);
-    return qualifyFutureFunctions(normalized.replace(/\r\n|\r|\n/g, " "));
+    // `@x` is persisted as `_xlfn.SINGLE(x)`; encoding first lets the
+    // future-function pass add the prefix.
+    return qualifyFutureFunctions(encodeImplicitIntersection(normalized.replace(/\r\n|\r|\n/g, " ")));
 }
 function escapeXmlBase(value) {
     return sanitizeXmlText(value)
@@ -1976,6 +1996,11 @@ const buildSheetViewsXml = (sheet) => {
         zoomScale !== 100) {
         attrs.push(`zoomScale="${zoomScale}"`);
     }
+    // `rightToLeft` — only an explicit true is written (Excel's default is
+    // LTR and the attribute is omitted), mirroring the Rust exporter.
+    if (sheet.rightToLeft) {
+        attrs.push(`rightToLeft="1"`);
+    }
     const panes = [];
     const frozenRows = sheet.frozenRowCount ?? 0;
     const frozenColumns = sheet.frozenColumnCount ?? 0;
@@ -2230,6 +2255,57 @@ const sanitizeTableName = (name) => {
     }
     return cleaned;
 };
+/**
+ * `SUBTOTAL()` function numbers (the 101+ "ignore hidden rows" family Excel
+ * writes into totals-row cells) → `totalsRowFunction`.
+ */
+const SUBTOTAL_TOTALS_ROW_FUNCTIONS = {
+    "101": "average",
+    "102": "countNums",
+    "103": "count",
+    "104": "max",
+    "105": "min",
+    "107": "stdDev",
+    "109": "sum",
+    "110": "var",
+};
+/**
+ * Totals-row metadata for one `<tableColumn>`. Explicit column metadata
+ * (imported from Excel, or set by the host) wins — an explicit `none` means
+ * "no totals function" and is not second-guessed from the cell (the Rust
+ * exporter's `totals_for_column` agrees). Otherwise it is derived from the
+ * totals-row cell so tables whose totals row was added in-app (a "Total"
+ * label + `=SUBTOTAL(109,[Col])` per numeric column) open in Excel with the
+ * matching function selected in the totals dropdown. A formula that is not
+ * a plain `SUBTOTAL(n, ref)` is left to the cell.
+ */
+const resolveTableColumnTotals = (column, totalsCell) => {
+    if (column?.totalsRowLabel) {
+        return { totalsRowLabel: column.totalsRowLabel };
+    }
+    if (column?.totalsRowFunction) {
+        if (column.totalsRowFunction === "none") {
+            return undefined;
+        }
+        if (column.totalsRowFunction === "custom" && !column.totalsRowFormula) {
+            return undefined;
+        }
+        return {
+            totalsRowFunction: column.totalsRowFunction,
+            totalsRowFormula: column.totalsRowFormula ?? undefined,
+        };
+    }
+    if (!totalsCell)
+        return undefined;
+    const formula = getExtendedValueFormula(getCellUserEnteredValue(totalsCell));
+    if (formula) {
+        const match = /^=?\s*SUBTOTAL\(\s*(\d{3})\s*,[^,]*\)\s*$/i.exec(formula);
+        const fn = match ? SUBTOTAL_TOTALS_ROW_FUNCTIONS[match[1]] : undefined;
+        return fn ? { totalsRowFunction: fn } : undefined;
+    }
+    const label = getExtendedValueString(getCellUserEnteredValue(totalsCell));
+    return label && label.trim() !== "" ? { totalsRowLabel: label } : undefined;
+};
 const buildTableXml = (table, rows, sourceSharedStrings, styleBuilder) => {
     const rangeRef = table.ref;
     const columnCount = Math.max(table.columns?.length ?? 0, (table.range.endColumnIndex ?? table.range.startColumnIndex) -
@@ -2275,6 +2351,7 @@ const buildTableXml = (table, rows, sourceSharedStrings, styleBuilder) => {
         // Fallback to table.columns name or generic name
         return table.columns?.[index]?.name ?? `Column${index + 1}`;
     });
+    const totalsRowIndex = table.range.endRowIndex;
     const tableColumns = `<tableColumns count="${columnCount}">${columnNames
         .map((name, idx) => {
         const columnFormula = table.columns?.[idx]?.formula;
@@ -2284,7 +2361,22 @@ const buildTableXml = (table, rows, sourceSharedStrings, styleBuilder) => {
         const formulaXml = normalizedFormula
             ? `<calculatedColumnFormula>${escapeXmlText(stripFormula(normalizedFormula))}</calculatedColumnFormula>`
             : "";
-        return `<tableColumn id="${idx + 1}" name="${escapeXmlAttr(name)}">${formulaXml}</tableColumn>`;
+        // Explicit per-column totals metadata exports whether or not the totals
+        // row is shown: Excel keeps it on a table whose totals row is toggled
+        // off so re-enabling restores each column's choice. Deriving it from
+        // the last row only applies when that row IS the totals row.
+        const totals = resolveTableColumnTotals(table.columns?.[idx], totalsRowCount > 0
+            ? rows[totalsRowIndex]?.values?.[table.range.startColumnIndex + idx]
+            : undefined);
+        const totalsAttrs = totals?.totalsRowLabel
+            ? ` totalsRowLabel="${escapeXmlAttr(totals.totalsRowLabel)}"`
+            : totals?.totalsRowFunction
+                ? ` totalsRowFunction="${totals.totalsRowFunction}"`
+                : "";
+        const totalsFormulaXml = totals?.totalsRowFunction === "custom" && totals.totalsRowFormula
+            ? `<totalsRowFormula>${escapeXmlText(stripFormula(normalizeCalculatedColumnFormula(totals.totalsRowFormula, table)))}</totalsRowFormula>`
+            : "";
+        return `<tableColumn id="${idx + 1}" name="${escapeXmlAttr(name)}"${totalsAttrs}>${formulaXml}${totalsFormulaXml}</tableColumn>`;
     })
         .join("")}</tableColumns>`;
     const isBuiltInStyle = table.theme && /^TableStyle(Light|Medium|Dark)\d+$/.test(table.theme);
@@ -2332,6 +2424,106 @@ const buildWorksheetAutoFilterXml = (sheet, rows, styleBuilder) => {
     }
     return `<autoFilter ref="${ref}"/>`;
 };
+/** `CT_SheetProtection` boolean attributes in Excel's attribute order. */
+const SHEET_PROTECTION_FLAG_ATTRS = [
+    "sheet",
+    "objects",
+    "scenarios",
+    "formatCells",
+    "formatColumns",
+    "formatRows",
+    "insertColumns",
+    "insertRows",
+    "insertHyperlinks",
+    "deleteColumns",
+    "deleteRows",
+    "selectLockedCells",
+    "sort",
+    "autoFilter",
+    "pivotTables",
+    "selectUnlockedCells",
+];
+/**
+ * `<sheetProtection …/>` from `Sheet.sheetProtection`: the password hash first
+ * (legacy `password` or the agile quartet, verbatim), then only the action
+ * flags the model carries (`true` → `"1"`, `false` → `"0"`, absent → omitted so
+ * Excel's schema default applies). Mirrors `rnc-export`'s `sheet_protection_xml`.
+ */
+const buildSheetProtectionElementXml = (protection) => {
+    const attrs = [];
+    if (protection.algorithmName) {
+        attrs.push(`algorithmName="${escapeXmlAttr(protection.algorithmName)}"`);
+    }
+    if (protection.hashValue) {
+        attrs.push(`hashValue="${escapeXmlAttr(protection.hashValue)}"`);
+    }
+    if (protection.saltValue) {
+        attrs.push(`saltValue="${escapeXmlAttr(protection.saltValue)}"`);
+    }
+    if (protection.spinCount != null) {
+        attrs.push(`spinCount="${protection.spinCount}"`);
+    }
+    if (protection.password) {
+        attrs.push(`password="${escapeXmlAttr(protection.password)}"`);
+    }
+    for (const flag of SHEET_PROTECTION_FLAG_ATTRS) {
+        const value = protection[flag];
+        if (typeof value === "boolean") {
+            attrs.push(`${flag}="${value ? 1 : 0}"`);
+        }
+    }
+    return attrs.length ? `<sheetProtection ${attrs.join(" ")}/>` : "";
+};
+/**
+ * The sheet's protection block — `<sheetProtection>` followed by
+ * `<protectedRanges>` — or `""` when the sheet is unprotected and has no
+ * allow-edit ranges. Ranges missing a bound (a sheet-wide `protect-sheet`
+ * entry only carries `sheetId`) have no `sqref` and are skipped; the `name`
+ * is the range's id, synthesized as `Range{n}` when absent (schema requires it).
+ */
+const buildSheetProtectionXml = (sheet, protectedRanges) => {
+    const protectionXml = sheet.sheetProtection
+        ? buildSheetProtectionElementXml(sheet.sheetProtection)
+        : "";
+    const rangeItems = [];
+    for (const protectedRange of protectedRanges ?? []) {
+        const range = protectedRange.range;
+        if (range.sheetId !== sheet.sheetId)
+            continue;
+        if (range.startRowIndex == null ||
+            range.endRowIndex == null ||
+            range.startColumnIndex == null ||
+            range.endColumnIndex == null) {
+            continue;
+        }
+        // Excel writes a single cell as `D10`, a block as `A2:C5`.
+        const isSingleCell = range.startRowIndex === range.endRowIndex &&
+            range.startColumnIndex === range.endColumnIndex;
+        const sqref = isSingleCell
+            ? cellToAddress({
+                rowIndex: range.startRowIndex,
+                columnIndex: range.startColumnIndex,
+            })
+            : cellRangeToAddress(undefined, {
+                startRowIndex: range.startRowIndex,
+                endRowIndex: range.endRowIndex,
+                startColumnIndex: range.startColumnIndex,
+                endColumnIndex: range.endColumnIndex,
+            });
+        if (!sqref)
+            continue;
+        const id = protectedRange.protectedRangeId;
+        const name = id != null && String(id) !== "" ? String(id) : `Range${rangeItems.length + 1}`;
+        const securityDescriptor = protectedRange.securityDescriptor
+            ? ` securityDescriptor="${escapeXmlAttr(protectedRange.securityDescriptor)}"`
+            : "";
+        rangeItems.push(`<protectedRange sqref="${escapeXmlAttr(sqref)}" name="${escapeXmlAttr(name)}"${securityDescriptor}/>`);
+    }
+    const rangesXml = rangeItems.length
+        ? `<protectedRanges>${rangeItems.join("")}</protectedRanges>`
+        : "";
+    return `${protectionXml}${rangesXml}`;
+};
 const buildSheetPropertiesXml = (sheet) => {
     const tabColor = serializeColorXml(sheet.tabColor ?? undefined);
     // <outlinePr> mirrors the sheet's `outlinePr` setting; both attrs
@@ -2348,11 +2540,105 @@ const buildSheetPropertiesXml = (sheet) => {
     const outlineXml = outlineAttrs.length
         ? `<outlinePr ${outlineAttrs.join(" ")}/>`
         : "";
-    if (!tabColor && !outlineXml)
+    // `<pageSetUpPr fitToPage="1">` is what makes Excel honour
+    // `<pageSetup fitToWidth/fitToHeight>` instead of `scale`.
+    const pageSetUpPrXml = sheet.printSettings?.pageSetup?.fitToPage
+        ? `<pageSetUpPr fitToPage="1"/>`
+        : "";
+    if (!tabColor && !outlineXml && !pageSetUpPrXml)
         return "";
-    const inner = `${tabColor ? `<tabColor ${tabColor}/>` : ""}${outlineXml}`;
+    const inner = `${tabColor ? `<tabColor ${tabColor}/>` : ""}${outlineXml}${pageSetUpPrXml}`;
     return `<sheetPr>${inner}</sheetPr>`;
 };
+const xmlBoolAttr = (name, value) => value == null ? "" : ` ${name}="${value ? "1" : "0"}"`;
+const xmlNumAttr = (name, value) => typeof value === "number" && Number.isFinite(value)
+    ? ` ${name}="${value}"`
+    : "";
+/**
+ * The `CT_Worksheet` print tail — `<printOptions>`, `<pageMargins>`,
+ * `<pageSetup>`, `<headerFooter>`, `<rowBreaks>`, `<colBreaks>` — in schema
+ * order (after `<hyperlinks>`, before `<drawing>`). `<pageMargins>` is
+ * mandatory in practice (Excel always writes it), so the default margins go
+ * out when the sheet has none of its own.
+ */
+const buildPrintSettingsXml = (print) => {
+    const parts = [];
+    const options = print?.printOptions;
+    const optionAttrs = xmlBoolAttr("horizontalCentered", options?.horizontalCentered) +
+        xmlBoolAttr("verticalCentered", options?.verticalCentered) +
+        xmlBoolAttr("headings", options?.headings) +
+        xmlBoolAttr("gridLines", options?.gridLines);
+    if (optionAttrs)
+        parts.push(`<printOptions${optionAttrs}/>`);
+    const margins = print?.pageMargins;
+    parts.push(margins &&
+        Object.values(margins).some((v) => typeof v === "number")
+        ? `<pageMargins left="${margins.left ?? 0.7}" right="${margins.right ?? 0.7}" top="${margins.top ?? 0.75}" bottom="${margins.bottom ?? 0.75}" header="${margins.header ?? 0.3}" footer="${margins.footer ?? 0.3}"/>`
+        : DEFAULT_PAGE_MARGINS);
+    const setup = print?.pageSetup;
+    if (setup) {
+        // Excel keeps `firstPageNumber` as a dormant value until the user picks
+        // a first page number (`useFirstPageNumber="1"`); a bare number means
+        // "Auto", so the flag is written only when the model has it on.
+        const useFirst = setup.useFirstPageNumber === true ? true : undefined;
+        const setupAttrs = xmlNumAttr("paperSize", setup.paperSize) +
+            xmlNumAttr("scale", setup.scale) +
+            xmlNumAttr("firstPageNumber", setup.firstPageNumber) +
+            xmlNumAttr("fitToWidth", setup.fitToWidth) +
+            xmlNumAttr("fitToHeight", setup.fitToHeight) +
+            (setup.pageOrder ? ` pageOrder="${setup.pageOrder}"` : "") +
+            (setup.orientation ? ` orientation="${setup.orientation}"` : "") +
+            xmlBoolAttr("blackAndWhite", setup.blackAndWhite) +
+            xmlBoolAttr("draft", setup.draft) +
+            xmlBoolAttr("useFirstPageNumber", useFirst);
+        if (setupAttrs)
+            parts.push(`<pageSetup${setupAttrs}/>`);
+    }
+    const hf = print?.headerFooter;
+    if (hf && !isHeaderFooterEmpty(hf)) {
+        const hfAttrs = xmlBoolAttr("differentOddEven", hf.differentOddEven) +
+            xmlBoolAttr("differentFirst", hf.differentFirst) +
+            xmlBoolAttr("scaleWithDoc", hf.scaleWithDoc) +
+            xmlBoolAttr("alignWithMargins", hf.alignWithMargins);
+        const children = [
+            "oddHeader",
+            "oddFooter",
+            "evenHeader",
+            "evenFooter",
+            "firstHeader",
+            "firstFooter",
+        ]
+            .map((key) => {
+            const text = hf[key];
+            return typeof text === "string" && text
+                ? `<${key}>${escapeXmlText(text)}</${key}>`
+                : "";
+        })
+            .join("");
+        parts.push(children
+            ? `<headerFooter${hfAttrs}>${children}</headerFooter>`
+            : `<headerFooter${hfAttrs}/>`);
+    }
+    const breaks = (ids, max) => {
+        const valid = Array.from(new Set((ids ?? []).filter((id) => Number.isInteger(id) && id > 0))).sort((a, b) => a - b);
+        if (!valid.length)
+            return "";
+        return valid
+            .map((id) => `<brk id="${id}" max="${max}" man="1"/>`)
+            .join("");
+    };
+    const rowBrks = breaks(print?.rowBreaks, 16383);
+    if (rowBrks) {
+        const count = rowBrks.split("<brk ").length - 1;
+        parts.push(`<rowBreaks count="${count}" manualBreakCount="${count}">${rowBrks}</rowBreaks>`);
+    }
+    const colBrks = breaks(print?.columnBreaks, 1048575);
+    if (colBrks) {
+        const count = colBrks.split("<brk ").length - 1;
+        parts.push(`<colBreaks count="${count}" manualBreakCount="${count}">${colBrks}</colBreaks>`);
+    }
+    return parts.join("");
+};
 const buildFilterColumnsXml = (filterSpecs, range, rows, headerRow = true, totalRow = false, styleBuilder) => {
     if (!filterSpecs?.length)
         return "";
@@ -2420,15 +2706,26 @@ const gridRangeToRef = (range) => {
 };
 const groupEmbedsBySheet = (embeds) => {
     const result = new Map();
-    for (const embed of embeds ?? []) {
+    (embeds ?? []).forEach((embed, order) => {
         if (!embed.position?.overlayPosition)
-            continue;
+            return;
         if (embed.spec?.type !== "image")
-            continue;
+            return;
         const overlay = embed.position.overlayPosition;
+        const imageSpec = embed.spec;
+        const adjustments = {
+            crop: imageSpec.crop ?? undefined,
+            brightness: imageSpec.brightness ?? undefined,
+            contrast: imageSpec.contrast ?? undefined,
+            transparency: imageSpec.transparency ?? undefined,
+        };
         const placement = {
             kind: "embed",
-            imageUrl: embed.spec.imageUrl,
+            imageUrl: imageSpec.imageUrl,
+            adjustments: Object.values(adjustments).some((v) => v !== undefined)
+                ? adjustments
+                : undefined,
+            order,
             rowIndex: overlay.anchorCell.rowIndex,
             columnIndex: overlay.anchorCell.columnIndex,
             offsetX: overlay.offsetXPixels ?? 0,
@@ -2439,19 +2736,20 @@ const groupEmbedsBySheet = (embeds) => {
         const list = result.get(embed.position.sheetId) ?? [];
         list.push(placement);
         result.set(embed.position.sheetId, list);
-    }
+    });
     return result;
 };
 const groupTextBoxesBySheet = (embeds) => {
     const result = new Map();
-    for (const embed of embeds ?? []) {
+    (embeds ?? []).forEach((embed, order) => {
         if (!embed.position?.overlayPosition)
-            continue;
+            return;
         if (embed.spec?.type !== "textbox")
-            continue;
+            return;
         const overlay = embed.position.overlayPosition;
         const placement = {
             textBox: embed,
+            order,
             rowIndex: overlay.anchorCell.rowIndex,
             columnIndex: overlay.anchorCell.columnIndex,
             offsetX: overlay.offsetXPixels ?? 0,
@@ -2462,19 +2760,20 @@ const groupTextBoxesBySheet = (embeds) => {
         const list = result.get(embed.position.sheetId) ?? [];
         list.push(placement);
         result.set(embed.position.sheetId, list);
-    }
+    });
     return result;
 };
 const groupShapesBySheet = (embeds) => {
     const result = new Map();
-    for (const embed of embeds ?? []) {
+    (embeds ?? []).forEach((embed, order) => {
         if (!embed.position?.overlayPosition)
-            continue;
+            return;
         if (embed.spec?.type !== "shape")
-            continue;
+            return;
         const overlay = embed.position.overlayPosition;
         const placement = {
             shape: embed,
+            order,
             rowIndex: overlay.anchorCell.rowIndex,
             columnIndex: overlay.anchorCell.columnIndex,
             offsetX: overlay.offsetXPixels ?? 0,
@@ -2485,7 +2784,7 @@ const groupShapesBySheet = (embeds) => {
         const list = result.get(embed.position.sheetId) ?? [];
         list.push(placement);
         result.set(embed.position.sheetId, list);
-    }
+    });
     return result;
 };
 const groupChartsBySheet = (charts) => {
@@ -3118,20 +3417,32 @@ const buildDrawingParts = async ({ placements, textBoxes, shapes = [], startImag
         }));
         frameId += 1;
     }
+    // Embeds (text boxes, shapes, images) keep the host's `embeds` order in the
+    // drawing part — anchor order IS Excel's z-order, so an image drawn over a
+    // shape must be emitted after it regardless of kind. Placements without an
+    // order (in-cell images) go last, in their own order.
+    const embedAnchors = [];
+    const orderOf = (order) => order ?? Number.MAX_SAFE_INTEGER;
     for (const placement of textBoxes) {
-        anchors.push(createTextBoxAnchor({
-            sheet,
-            placement,
-            frameId,
-        }));
+        embedAnchors.push({
+            order: orderOf(placement.order),
+            xml: createTextBoxAnchor({
+                sheet,
+                placement,
+                frameId,
+            }),
+        });
         frameId += 1;
     }
     for (const placement of shapes) {
-        anchors.push(createShapeAnchor({
-            sheet,
-            placement,
-            frameId,
-        }));
+        embedAnchors.push({
+            order: orderOf(placement.order),
+            xml: createShapeAnchor({
+                sheet,
+                placement,
+                frameId,
+            }),
+        });
         frameId += 1;
     }
     for (const placement of placements) {
@@ -3148,15 +3459,21 @@ const buildDrawingParts = async ({ placements, textBoxes, shapes = [], startImag
             extension: buffer.extension,
         });
         const relId = relationships.add(IMAGE_REL_TYPE, `../media/image${imageIndex}.${buffer.extension}`);
-        anchors.push(createTwoCellAnchor({
-            sheet,
-            placement,
-            relId,
-            pictureId,
-        }));
+        embedAnchors.push({
+            order: orderOf(placement.order),
+            xml: createTwoCellAnchor({
+                sheet,
+                placement,
+                relId,
+                pictureId,
+            }),
+        });
         imageIndex += 1;
         pictureId += 1;
     }
+    embedAnchors.sort((a, b) => a.order - b.order);
+    for (const entry of embedAnchors)
+        anchors.push(entry.xml);
     const drawingXml = `${XML_DECLARATION}<xdr:wsDr xmlns:xdr="http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing" xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:r="${REL_NS}">${anchors.join("")}</xdr:wsDr>`;
     return {
         xml: drawingXml,
@@ -3190,7 +3507,53 @@ const createTwoCellAnchor = ({ placement, relId, pictureId, sheet, }) => {
     });
     const fromXml = `<xdr:from><xdr:col>${fromColumn}</xdr:col><xdr:colOff>${Math.round(offsetX * EMUS_PER_PIXEL)}</xdr:colOff><xdr:row>${fromRow}</xdr:row><xdr:rowOff>${Math.round(offsetY * EMUS_PER_PIXEL)}</xdr:rowOff></xdr:from>`;
     const toXml = `<xdr:to><xdr:col>${toColumn.index}</xdr:col><xdr:colOff>${Math.round(toColumn.offset * EMUS_PER_PIXEL)}</xdr:colOff><xdr:row>${toRow.index}</xdr:row><xdr:rowOff>${Math.round(toRow.offset * EMUS_PER_PIXEL)}</xdr:rowOff></xdr:to>`;
-    return `<xdr:twoCellAnchor editAs="oneCell">${fromXml}${toXml}<xdr:pic><xdr:nvPicPr><xdr:cNvPr id="${pictureId}" name="Picture ${pictureId}"/><xdr:cNvPicPr/></xdr:nvPicPr><xdr:blipFill><a:blip r:embed="${relId}"/><a:stretch><a:fillRect/></a:stretch></xdr:blipFill><xdr:spPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="${Math.round(widthPx * EMUS_PER_PIXEL)}" cy="${Math.round(heightPx * EMUS_PER_PIXEL)}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom></xdr:spPr></xdr:pic><xdr:clientData/></xdr:twoCellAnchor>`;
+    const { blipChildren, srcRectXml } = buildPictureAdjustmentsXml(placement.adjustments);
+    const blipXml = blipChildren
+        ? `<a:blip r:embed="${relId}">${blipChildren}</a:blip>`
+        : `<a:blip r:embed="${relId}"/>`;
+    return `<xdr:twoCellAnchor editAs="oneCell">${fromXml}${toXml}<xdr:pic><xdr:nvPicPr><xdr:cNvPr id="${pictureId}" name="Picture ${pictureId}"/><xdr:cNvPicPr/></xdr:nvPicPr><xdr:blipFill>${blipXml}${srcRectXml}<a:stretch><a:fillRect/></a:stretch></xdr:blipFill><xdr:spPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="${Math.round(widthPx * EMUS_PER_PIXEL)}" cy="${Math.round(heightPx * EMUS_PER_PIXEL)}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom></xdr:spPr></xdr:pic><xdr:clientData/></xdr:twoCellAnchor>`;
+};
+/** Fraction (0…1) → DrawingML per-mille percent (100000 = 100%). */
+const fractionToPct = (value) => Math.round(Math.max(-1, Math.min(1, value)) * 100000);
+/**
+ * `<a:blip>` children (`<a:alphaModFix>`, `<a:lum>`) and the `<a:srcRect>`
+ * sibling for an image's picture-format adjustments; both empty when the
+ * spec carries none.
+ */
+const buildPictureAdjustmentsXml = (adjustments) => {
+    if (!adjustments)
+        return { blipChildren: "", srcRectXml: "" };
+    let blipChildren = "";
+    const { transparency, brightness, contrast, crop } = adjustments;
+    if (typeof transparency === "number" && transparency > 0) {
+        blipChildren += `<a:alphaModFix amt="${fractionToPct(1 - Math.min(1, transparency))}"/>`;
+    }
+    const hasBrightness = typeof brightness === "number" && brightness !== 0;
+    const hasContrast = typeof contrast === "number" && contrast !== 0;
+    if (hasBrightness || hasContrast) {
+        blipChildren += `<a:lum${hasBrightness ? ` bright="${fractionToPct(brightness)}"` : ""}${hasContrast ? ` contrast="${fractionToPct(contrast)}"` : ""}/>`;
+    }
+    let srcRectXml = "";
+    if (crop) {
+        const edges = ["l", "t", "r", "b"]
+            .map((edge) => {
+            const value = {
+                l: crop.left,
+                t: crop.top,
+                r: crop.right,
+                b: crop.bottom,
+            }[edge];
+            // Negative edges are Excel's "out-crop" (padding around the
+            // bitmap) and round-trip like positive ones.
+            return typeof value === "number" && Number.isFinite(value) && value !== 0
+                ? ` ${edge}="${fractionToPct(value)}"`
+                : "";
+        })
+            .join("");
+        if (edges)
+            srcRectXml = `<a:srcRect${edges}/>`;
+    }
+    return { blipChildren, srcRectXml };
 };
 const createChartAnchor = ({ placement, relId, frameId, sheet, }) => {
     const fromRow = Math.max(0, placement.rowIndex - 1);
@@ -3857,7 +4220,10 @@ const buildWorkbookXml = (sheets, sheetRelIds, sheetNames, namedRanges, iterativ
     sheets.forEach((sheet, index) => {
         sheetNameById.set(sheet.sheetId ?? index + 1, sheetNames[index]);
     });
-    const definedNamesXml = buildDefinedNamesXml(namedRanges, sheetNameById);
+    const definedNamesXml = buildDefinedNamesXml(namedRanges, sheetNameById, sheets.map((sheet, index) => ({
+        sheetName: sheetNames[index] ?? `Sheet${index + 1}`,
+        printSettings: sheet.printSettings,
+    })));
     const calcPrXml = buildCalcPrXml(iterativeCalculationOptions);
     const slicerCachesXml = buildWorkbookSlicerCachesXml(slicerCacheRelIds);
     // Phase D2 — <pivotCaches> element. Each <pivotCache> pairs a
@@ -3886,12 +4252,48 @@ const buildWorkbookXml = (sheets, sheetRelIds, sheetNames, namedRanges, iterativ
         : `<workbookPr/>`;
     return `${XML_DECLARATION}<workbook xmlns="${WORKSHEET_NS}" xmlns:r="${REL_NS}">${workbookPrXml}${calcPrXml}<bookViews><workbookView activeTab="0" firstSheet="0"/></bookViews><sheets>${sheetEntries}</sheets>${definedNamesXml}${externalReferencesXml}${pivotCachesXml}${slicerCachesXml}</workbook>`;
 };
-const buildDefinedNamesXml = (namedRanges, sheetNameById) => {
-    if (!namedRanges?.length)
-        return "";
+const buildDefinedNamesXml = (namedRanges, sheetNameById, printScopes = []) => {
     const entries = [];
-    for (const namedRange of namedRanges) {
-        if (!namedRange?.name)
+    // The builtin print names are sheet-scoped (`localSheetId` = position in
+    // `<sheets>`); they come from `sheet.printSettings`, never from
+    // `namedRanges` (a global `_xlnm.Print_Area` makes Excel repair the file).
+    // Documents imported before `printSettings` existed still carry the print
+    // area as a `_xlnm.Print_Area` named range on the sheet; it is converted
+    // to the sheet-scoped name here unless the sheet already has a print area.
+    const sheetIndexByName = new Map(printScopes.map(({ sheetName }, index) => [sheetName, index]));
+    const legacyPrintAreas = new Map();
+    for (const namedRange of namedRanges ?? []) {
+        if (namedRange?.name !== PRINT_AREA_NAME || !namedRange.range?.sheetId) {
+            continue;
+        }
+        const sheetName = sheetNameById.get(namedRange.range.sheetId);
+        const index = sheetName ? sheetIndexByName.get(sheetName) : undefined;
+        if (index == null)
+            continue;
+        legacyPrintAreas.set(index, [
+            ...(legacyPrintAreas.get(index) ?? []),
+            namedRange.range,
+        ]);
+    }
+    printScopes.forEach(({ sheetName, printSettings }, index) => {
+        const printArea = printSettings?.printArea?.length
+            ? printSettings.printArea
+            : legacyPrintAreas.get(index);
+        const area = printArea?.length
+            ? buildPrintAreaFormula(sheetName, printArea)
+            : undefined;
+        if (area) {
+            entries.push(`<definedName name="${PRINT_AREA_NAME}" localSheetId="${index}">${escapeXmlText(area)}</definedName>`);
+        }
+        const titles = printSettings?.printTitles
+            ? buildPrintTitlesFormula(sheetName, printSettings.printTitles)
+            : undefined;
+        if (titles) {
+            entries.push(`<definedName name="${PRINT_TITLES_NAME}" localSheetId="${index}">${escapeXmlText(titles)}</definedName>`);
+        }
+    });
+    for (const namedRange of namedRanges ?? []) {
+        if (!namedRange?.name || isBuiltinPrintName(namedRange.name))
             continue;
         const hiddenAttr = namedRange.hidden ? ` hidden="1"` : "";
         if (namedRange.range?.sheetId) {