@rowsncolumns/toolkit 24.4.1

package/dist/esm/exporter/xlsx/chart-builder.js

@@ -0,0 +1,1805 @@
+import { cellRangeToAddress, sanitizeSheetName } from "@rowsncolumns/utils";
+import { XMLBuilder } from "fast-xml-parser";
+import { area_series, bubble_series, chart_template, column_json, column_series, donut_json, line_series, scatter_json, scatter_series, static_title, } from "./chart-templates";
+const XML_DECLARATION = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`;
+const INVALID_XML_CHAR_REGEX = /[\u0000-\u0008\u000B\u000C\u000E-\u001F]/g;
+const chartBuilder = new XMLBuilder({
+    ignoreAttributes: false,
+    attributesGroupName: "a$",
+    textNodeName: "t$",
+    suppressEmptyNode: true,
+});
+const sanitizeXmlText = (value) => value ? value.replace(INVALID_XML_CHAR_REGEX, "") : value;
+const cloneTemplate = (template) => JSON.parse(JSON.stringify(template));
+const removeProp = (obj, key) => {
+    delete obj[key];
+};
+const normalizeFormula = (formula) => {
+    const trimmed = formula.startsWith("=") ? formula.slice(1) : formula;
+    return sanitizeXmlText(trimmed).replace(/\r\n|\r|\n/g, " ");
+};
+const hasPropertyReference = (formula) => {
+    if (!formula)
+        return false;
+    // Detects cell references with property access: A1.property, $A$1.nested.value, etc.
+    const propertyReferencePattern = /[$]?[A-Za-z]{1,3}[$]?[1-9][0-9]*\./;
+    return propertyReferencePattern.test(formula);
+};
+const formatRangeRef = (range, sheetNameById) => {
+    if (!range)
+        return undefined;
+    const sheetName = sheetNameById.get(range.sheetId);
+    return cellRangeToAddress(sheetName, range);
+};
+/**
+ * A1 reference over EVERY range of a (possibly multi-area) source list,
+ * joined with the union operator — `'Sheet'!$E$19,'Sheet'!$E$26,…`. The old
+ * first-range-only behavior silently truncated discontiguous series.
+ */
+const formatSourcesRef = (sources, sheetNameById) => {
+    if (!sources?.length)
+        return undefined;
+    const parts = sources
+        .map((range) => formatRangeRef(range, sheetNameById))
+        .filter((ref) => Boolean(ref));
+    return parts.length ? parts.join(",") : undefined;
+};
+const seriesCategoryRef = (entry, sheetNameById) => formatSourcesRef(entry?.categorySources, sheetNameById);
+const buildSeriesLabel = (label, sheetName, labelRef) => {
+    // A captured source reference (`<c:tx><c:strRef>`) wins over the literal:
+    // emitting the ref without a cache lets Excel resolve the live series name
+    // on open, instead of freezing a possibly-generic literal.
+    if (labelRef) {
+        return {
+            "c:tx": {
+                "c:strRef": {
+                    "c:f": labelRef,
+                },
+            },
+        };
+    }
+    if (label === undefined || label === null || label === "")
+        return undefined;
+    // Numeric series headers (e.g. a year like 2024) can reach us as numbers
+    const text = typeof label === "string" ? label : String(label);
+    if (text.startsWith("=")) {
+        // If label contains property references (e.g., =A1.propertyName),
+        // treat it as static text instead of formula reference
+        if (hasPropertyReference(text)) {
+            return {
+                "c:tx": {
+                    "c:v": sanitizeXmlText(text),
+                },
+            };
+        }
+        const formula = normalizeFormula(text);
+        const resolved = sheetName && !formula.includes("!")
+            ? `${sanitizeSheetName(sheetName)}!${formula}`
+            : formula;
+        return {
+            "c:tx": {
+                "c:strRef": {
+                    "c:f": resolved,
+                },
+            },
+        };
+    }
+    return {
+        "c:tx": {
+            "c:v": sanitizeXmlText(text),
+        },
+    };
+};
+const buildColorNode = (color) => {
+    const normalized = color.startsWith("#") ? color.slice(1) : color;
+    const hex = normalized.length === 6
+        ? normalized
+        : normalized.slice(normalized.length - 6);
+    return {
+        "a:solidFill": {
+            "a:srgbClr": {
+                a$: {
+                    val: hex,
+                },
+            },
+        },
+    };
+};
+const normalizeHex = (color) => {
+    const stripped = color.startsWith("#") ? color.slice(1) : color;
+    return stripped.length === 6
+        ? stripped
+        : stripped.slice(stripped.length - 6);
+};
+/**
+ * Build an OOXML `<a:gradFill>` node from a series-level gradient
+ * descriptor. Matches the DrawingML schema:
+ *
+ *   <a:gradFill flip="none" rotWithShape="1">
+ *     <a:gsLst>
+ *       <a:gs pos="0"><a:srgbClr val="FF0000"/></a:gs>
+ *       <a:gs pos="100000"><a:srgbClr val="0000FF"/></a:gs>
+ *     </a:gsLst>
+ *     <a:lin ang="5400000" scaled="0"/>  <!-- or <a:path path="rect">…</a:path> -->
+ *   </a:gradFill>
+ *
+ * Positions are EMU per-mille (0..100000). Linear angle is in 60000ths
+ * of a degree (90° == 5400000) — Excel's chart angle convention runs
+ * clockwise from 12 o'clock, so the conversion is `deg * 60000`.
+ *
+ * Path gradients use `<a:path path="rect">` with a `<a:fillToRect>`
+ * child carrying the inset of the inner stop in EMU per-mille.
+ */
+const buildGradFillNode = (gradient) => {
+    if (!gradient?.stops?.length)
+        return null;
+    const gsList = gradient.stops.map((stop) => ({
+        a$: { pos: String(Math.round(Math.max(0, Math.min(1, stop.position)) * 100000)) },
+        "a:srgbClr": { a$: { val: normalizeHex(stop.color) } },
+    }));
+    const direction = {};
+    if (gradient.type === "path") {
+        const toEmu = (v) => v != null ? String(Math.round(v * 100000)) : "0";
+        direction["a:path"] = {
+            a$: { path: "rect" },
+            "a:fillToRect": {
+                a$: {
+                    l: toEmu(gradient.left),
+                    r: toEmu(gradient.right),
+                    t: toEmu(gradient.top),
+                    b: toEmu(gradient.bottom),
+                },
+            },
+        };
+    }
+    else {
+        const deg = ((gradient.degree ?? 0) % 360 + 360) % 360;
+        direction["a:lin"] = {
+            a$: {
+                ang: String(Math.round(deg * 60000)),
+                scaled: "0",
+            },
+        };
+    }
+    return {
+        a$: { flip: "none", rotWithShape: "1" },
+        "a:gsLst": { "a:gs": gsList },
+        ...direction,
+    };
+};
+/**
+ * Replace the series' shape-properties fill with a gradient when one
+ * is supplied. Strips any pre-existing solid/scheme fill so the
+ * gradient doesn't double up.
+ */
+const applySeriesGradient = (seriesNode, gradient) => {
+    if (!gradient)
+        return false;
+    const gradFill = buildGradFillNode(gradient);
+    if (!gradFill)
+        return false;
+    const spPr = seriesNode["c:spPr"];
+    if (!spPr)
+        return false;
+    delete spPr["a:solidFill"];
+    spPr["a:gradFill"] = gradFill;
+    return true;
+};
+/**
+ * Build the extension list for a series with invertIfNegative support.
+ * This adds the c14:invertSolidFillFmt extension for negative fill color.
+ */
+const buildSeriesExtLst = (negativeColor, uniqueId) => {
+    const extensions = [];
+    // Add unique ID extension (required by Excel)
+    extensions.push({
+        a$: {
+            uri: "{C3380CC4-5D6E-409C-BE32-E72D297353CC}",
+            "xmlns:c16": "http://schemas.microsoft.com/office/drawing/2014/chart",
+        },
+        "c16:uniqueId": {
+            a$: {
+                val: uniqueId,
+            },
+        },
+    });
+    // Add negative fill color extension if specified
+    if (negativeColor) {
+        const normalizedColor = negativeColor.startsWith("#")
+            ? negativeColor.slice(1)
+            : negativeColor;
+        const hex = normalizedColor.length === 6
+            ? normalizedColor
+            : normalizedColor.slice(normalizedColor.length - 6);
+        extensions.push({
+            a$: {
+                uri: "{6F2FDCE9-48DA-4B69-8628-5D25D57E5C99}",
+                "xmlns:c14": "http://schemas.microsoft.com/office/drawing/2007/8/2/chart",
+            },
+            "c14:invertSolidFillFmt": {
+                "c14:spPr": {
+                    "a:solidFill": {
+                        "a:srgbClr": {
+                            a$: {
+                                val: hex,
+                            },
+                        },
+                    },
+                    "a:ln": {
+                        "a:noFill": {},
+                    },
+                    "a:effectLst": {},
+                },
+            },
+        });
+    }
+    return {
+        "c:ext": extensions.length === 1 ? extensions[0] : extensions,
+    };
+};
+// ─── Round-trip helpers (textFormat, marker, dPt, inline values) ─────
+/**
+ * Build a `<c:txPr>` XML node from a ChartTextFormat. Returns
+ * `undefined` when the format has no settable properties so callers
+ * can skip emission. Used by axis, legend, title, and data-label
+ * blocks to preserve authored color/font on round-trip.
+ */
+const buildTxPrNode = (textFormat) => {
+    if (!textFormat)
+        return undefined;
+    const defRPr = { a$: {} };
+    if (typeof textFormat.fontSize === "number") {
+        // ChartTextFormat stores points; OOXML stores 100ths of a point.
+        defRPr.a$.sz = String(Math.round(textFormat.fontSize * 100));
+    }
+    if (textFormat.bold)
+        defRPr.a$.b = "1";
+    if (textFormat.italic)
+        defRPr.a$.i = "1";
+    if (textFormat.underline)
+        defRPr.a$.u = "sng";
+    if (textFormat.strikethrough)
+        defRPr.a$.strike = "sngStrike";
+    if (textFormat.color) {
+        const hex = String(textFormat.color).replace(/^#/, "").toUpperCase();
+        defRPr["a:solidFill"] = {
+            "a:srgbClr": { a$: { val: hex } },
+        };
+    }
+    if (textFormat.fontFamily) {
+        defRPr["a:latin"] = { a$: { typeface: textFormat.fontFamily } };
+    }
+    // Only emit when we wrote something useful — otherwise Excel rejects
+    // an empty defRPr.
+    const hasAttrs = Object.keys(defRPr.a$).length > 0;
+    const hasChildren = Object.keys(defRPr).some((k) => k !== "a$");
+    if (!hasAttrs && !hasChildren)
+        return undefined;
+    return {
+        "a:bodyPr": {
+            a$: {
+                rot: "0",
+                spcFirstLastPara: "1",
+                vertOverflow: "ellipsis",
+                wrap: "square",
+                anchor: "ctr",
+                anchorCtr: "1",
+            },
+        },
+        "a:lstStyle": {},
+        "a:p": {
+            "a:pPr": { "a:defRPr": defRPr },
+            "a:endParaRPr": { a$: { lang: "en-US" } },
+        },
+    };
+};
+/**
+ * Build a `<c:strLit>` inline category block from an array of values.
+ * Used when a chart's category axis is embedded literally in the chart
+ * XML (e.g. Event Budget's `["Estimated", "Actual"]`) instead of
+ * referencing the sheet.
+ */
+const buildInlineStrLit = (values) => ({
+    "c:strLit": {
+        "c:ptCount": { a$: { val: String(values.length) } },
+        "c:pt": values.map((v, i) => ({
+            a$: { idx: String(i) },
+            "c:v": sanitizeXmlText(String(v)),
+        })),
+    },
+});
+/**
+ * Build a `<c:numLit>` inline numeric block from values. Used for
+ * inline-value series (rare but legal in OOXML).
+ */
+const buildInlineNumLit = (values) => ({
+    "c:numLit": {
+        "c:formatCode": "General",
+        "c:ptCount": { a$: { val: String(values.length) } },
+        "c:pt": values.map((v, i) => ({
+            a$: { idx: String(i) },
+            "c:v": typeof v === "number" ? String(v) : Number(v).toString(),
+        })),
+    },
+});
+/**
+ * Build a `<c:marker>` node from a ChartData.marker spec. Returns
+ * `undefined` when the marker carries no information.
+ */
+const buildMarkerNode = (marker) => {
+    if (!marker)
+        return undefined;
+    const node = {};
+    if (marker.symbol) {
+        node["c:symbol"] = { a$: { val: marker.symbol } };
+    }
+    if (typeof marker.size === "number") {
+        node["c:size"] = { a$: { val: String(Math.round(marker.size)) } };
+    }
+    if (marker.color) {
+        node["c:spPr"] = {
+            "a:solidFill": buildColorNode(marker.color)["a:solidFill"],
+        };
+    }
+    return Object.keys(node).length ? node : undefined;
+};
+/**
+ * Build a `<c:dPt>` array from per-point color overrides. Each entry
+ * pins a category index to a different fill — Gantt-style charts use
+ * this to colour each task individually.
+ */
+const buildDataPointNodes = (dataPointColors) => {
+    if (!dataPointColors || !dataPointColors.length)
+        return undefined;
+    return dataPointColors.map((dp) => ({
+        "c:idx": { a$: { val: String(dp.idx) } },
+        "c:invertIfNegative": { a$: { val: "0" } },
+        "c:bubble3D": { a$: { val: "0" } },
+        "c:spPr": {
+            "a:solidFill": buildColorNode(dp.color)["a:solidFill"],
+            "a:ln": { "a:noFill": {} },
+        },
+    }));
+};
+/**
+ * Apply transparent fill to a series spPr node. Mirrors the
+ * `<a:noFill/>` form Excel uses for invisible "offset" bars (Gantt
+ * lag series). Replaces any existing solidFill/gradFill.
+ */
+const applyNoFillToSeriesSpPr = (seriesNode) => {
+    const spPr = (seriesNode["c:spPr"] = seriesNode["c:spPr"] ?? {});
+    removeProp(spPr, "a:solidFill");
+    removeProp(spPr, "a:gradFill");
+    spPr["a:noFill"] = {};
+};
+/**
+ * Build the subtitle `<a:p>` paragraph node (fast-xml-parser object form)
+ * appended below the chart title inside the same `<c:rich>` block.
+ *
+ * Mirrors the legacy JS post-patcher (`chart-subtitle-patcher.ts`): the
+ * subtitle renders at ~70% of the title font size (9pt floor) in a muted
+ * `tx1` scheme colour. `titleSize` is in OOXML hundredths-of-a-point.
+ */
+const buildSubtitleParagraphNode = (subtitle, titleSize) => {
+    const subtitleSize = Math.max(900, Math.round(titleSize * 0.7));
+    return {
+        "a:pPr": {
+            "a:defRPr": {
+                a$: {
+                    sz: String(subtitleSize),
+                    b: "0",
+                    i: "0",
+                    u: "none",
+                    strike: "noStrike",
+                    kern: "1200",
+                    spc: "0",
+                    baseline: "0",
+                },
+                "a:solidFill": {
+                    "a:schemeClr": {
+                        a$: { val: "tx1" },
+                        "a:lumMod": { a$: { val: "65000" } },
+                        "a:lumOff": { a$: { val: "35000" } },
+                    },
+                },
+                "a:latin": { a$: { typeface: "+mn-lt" } },
+                "a:ea": { a$: { typeface: "+mn-ea" } },
+                "a:cs": { a$: { typeface: "+mn-cs" } },
+            },
+        },
+        "a:r": {
+            "a:rPr": { a$: { lang: "en-US", sz: String(subtitleSize), b: "0", i: "0" } },
+            "a:t": sanitizeXmlText(subtitle),
+        },
+    };
+};
+const applyChartTitle = (chartNode, title, titleTextFormat, subtitle) => {
+    if (!title)
+        return;
+    const titleBlock = cloneTemplate(static_title);
+    titleBlock["c:tx"]["c:rich"]["a:p"]["a:r"]["a:rPr"].a$.lang = "en-US";
+    titleBlock["c:tx"]["c:rich"]["a:p"]["a:r"]["a:t"] = sanitizeXmlText(title);
+    // Apply authored text format on the rich run's `a:rPr` so Excel
+    // preserves color/font on round-trip. We mutate the rPr directly
+    // (it's already inside the template's a:p > a:r).
+    if (titleTextFormat) {
+        const rPr = titleBlock["c:tx"]["c:rich"]["a:p"]["a:r"]["a:rPr"];
+        if (typeof titleTextFormat.fontSize === "number") {
+            rPr.a$.sz = String(Math.round(titleTextFormat.fontSize * 100));
+        }
+        if (titleTextFormat.bold)
+            rPr.a$.b = "1";
+        if (titleTextFormat.italic)
+            rPr.a$.i = "1";
+        if (titleTextFormat.color) {
+            const hex = String(titleTextFormat.color).replace(/^#/, "").toUpperCase();
+            rPr["a:solidFill"] = { "a:srgbClr": { a$: { val: hex } } };
+        }
+        if (titleTextFormat.fontFamily) {
+            rPr["a:latin"] = { a$: { typeface: titleTextFormat.fontFamily } };
+        }
+    }
+    // Append the subtitle as a SECOND `<a:p>` inside the title's `<c:rich>`,
+    // matching what the legacy JS post-patcher spliced in. Emitted natively
+    // here so no post-processing pass is needed. Scale relative to the
+    // authored title size (defaults to the template's 14pt → sz="1400").
+    if (subtitle && subtitle.trim().length > 0) {
+        const rich = titleBlock["c:tx"]["c:rich"];
+        const titlePara = rich["a:p"];
+        const titleSizeStr = (titlePara?.["a:pPr"]?.["a:defRPr"]?.a$?.sz ??
+            titlePara?.["a:r"]?.["a:rPr"]?.a$?.sz);
+        const titleSize = titleSizeStr && Number.isFinite(parseInt(titleSizeStr, 10))
+            ? parseInt(titleSizeStr, 10)
+            : 1400;
+        rich["a:p"] = [titlePara, buildSubtitleParagraphNode(subtitle, titleSize)];
+    }
+    chartNode["c:title"] = titleBlock;
+};
+const getPrimarySource = (entry) => entry?.sources?.[0];
+/**
+ * c15 extension namespace (Excel 2012+) — histogram / boxplot /
+ * waterfall / funnel charts are emitted with a `c:barChart` body
+ * inside `mc:Fallback` (so older Excel still renders something) plus a
+ * full c15 chart element inside `mc:Choice` (so Excel 2016+ renders
+ * the chart natively). See `buildC15AlternateContent` and the per-type
+ * builders below.
+ */
+const C15_NS = "http://schemas.microsoft.com/office/drawing/2012/chart";
+const C15_ELEMENT_NAMES = {
+    histogram: "c15:histogramChart",
+    boxplot: "c15:boxWhiskerChart",
+    waterfall: "c15:waterfallChart",
+    funnel: "c15:funnelChart",
+};
+const isC15ChartType = (t) => t === "histogram" || t === "boxplot" || t === "waterfall" || t === "funnel";
+const MC_NS = "http://schemas.openxmlformats.org/markup-compatibility/2006";
+/**
+ * Phase 5.5b — build the full c15:histogramChart body that Excel 2016+
+ * uses to render histograms natively. Lives inside `mc:Choice` next to
+ * the older `c:barChart` fallback (in `mc:Fallback`). Both share the
+ * `c:catAx`/`c:valAx` declared at `c:plotArea` level — c15 axId values
+ * are picked to match the bar chart's axId so Excel can resolve them.
+ */
+const buildC15HistogramChartNode = (spec, seriesRefs, series, domainRef, axIds) => {
+    const c15SeriesEntries = [];
+    seriesRefs.forEach((ref, index) => {
+        if (!ref)
+            return;
+        const seriesNode = {
+            "c15:idx": { a$: { val: String(index) } },
+            "c15:order": { a$: { val: String(index) } },
+        };
+        // Series title — only if the consumer set a non-formula dataLabel.
+        const dataLabel = series[index]?.dataLabel;
+        if (dataLabel && !dataLabel.startsWith("=")) {
+            seriesNode["c15:tx"] = {
+                "c15:v": dataLabel,
+            };
+        }
+        seriesNode["c15:val"] = {
+            "c15:numRef": {
+                "c15:f": ref,
+            },
+        };
+        c15SeriesEntries.push(seriesNode);
+    });
+    const histogramChart = {
+        "c15:varyColors": { a$: { val: "0" } },
+        "c15:ser": c15SeriesEntries.length === 1 ? c15SeriesEntries[0] : c15SeriesEntries,
+        "c15:axId": [
+            { a$: { val: axIds.catAxId } },
+            { a$: { val: axIds.valAxId } },
+        ],
+    };
+    // Bin configuration: explicit binCount when set, otherwise let Excel
+    // auto-bin (Sturges-like).
+    if (typeof spec?.binCount === "number" && spec.binCount > 0) {
+        histogramChart["c15:binCount"] = { a$: { val: String(spec.binCount) } };
+    }
+    else {
+        histogramChart["c15:binsAuto"] = { a$: { val: "1" } };
+    }
+    return histogramChart;
+};
+/**
+ * Phase 5.5b — c15:boxWhiskerChart body. Excel 2016+ renders box & whisker
+ * natively from this. Each series carries its raw values; Excel computes
+ * the quartiles + median + outliers from `c15:quartileMethod`.
+ */
+const buildC15BoxplotChartNode = (_spec, seriesRefs, series, domainRef, axIds) => {
+    const c15SeriesEntries = [];
+    seriesRefs.forEach((ref, index) => {
+        if (!ref)
+            return;
+        const seriesNode = {
+            "c15:idx": { a$: { val: String(index) } },
+            "c15:order": { a$: { val: String(index) } },
+            "c15:invertIfNegative": { a$: { val: "0" } },
+            "c15:bubble3D": { a$: { val: "0" } },
+        };
+        const dataLabel = series[index]?.dataLabel;
+        if (dataLabel && !dataLabel.startsWith("=")) {
+            seriesNode["c15:tx"] = { "c15:v": dataLabel };
+        }
+        if (domainRef) {
+            seriesNode["c15:cat"] = {
+                "c15:strRef": { "c15:f": domainRef },
+            };
+        }
+        seriesNode["c15:val"] = {
+            "c15:numRef": { "c15:f": ref },
+        };
+        c15SeriesEntries.push(seriesNode);
+    });
+    return {
+        "c15:varyColors": { a$: { val: "0" } },
+        "c15:ser": c15SeriesEntries.length === 1 ? c15SeriesEntries[0] : c15SeriesEntries,
+        "c15:showInnerPoints": { a$: { val: "0" } },
+        "c15:showOutlierPoints": { a$: { val: "1" } },
+        "c15:showMeanMarker": { a$: { val: "1" } },
+        "c15:showMeanLine": { a$: { val: "0" } },
+        "c15:quartileMethod": { a$: { val: "exclusive" } },
+        "c15:axId": [
+            { a$: { val: axIds.catAxId } },
+            { a$: { val: axIds.valAxId } },
+        ],
+    };
+};
+/**
+ * Phase 5.5b — c15:waterfallChart body. Each c15:ser carries one data
+ * point per category. Subtotals are marked at the series level via
+ * c15:dPt with c15:subTotal set; without these, Excel treats every
+ * point as a delta and the running cumulative is implicit.
+ */
+const buildC15WaterfallChartNode = (_spec, seriesRefs, series, domainRef, axIds) => {
+    const c15SeriesEntries = [];
+    seriesRefs.forEach((ref, index) => {
+        if (!ref)
+            return;
+        const seriesNode = {
+            "c15:idx": { a$: { val: String(index) } },
+            "c15:order": { a$: { val: String(index) } },
+        };
+        const dataLabel = series[index]?.dataLabel;
+        if (dataLabel && !dataLabel.startsWith("=")) {
+            seriesNode["c15:tx"] = { "c15:v": dataLabel };
+        }
+        if (domainRef) {
+            seriesNode["c15:cat"] = {
+                "c15:strRef": { "c15:f": domainRef },
+            };
+        }
+        seriesNode["c15:val"] = {
+            "c15:numRef": { "c15:f": ref },
+        };
+        c15SeriesEntries.push(seriesNode);
+    });
+    return {
+        "c15:varyColors": { a$: { val: "0" } },
+        "c15:ser": c15SeriesEntries.length === 1 ? c15SeriesEntries[0] : c15SeriesEntries,
+        "c15:axId": [
+            { a$: { val: axIds.catAxId } },
+            { a$: { val: axIds.valAxId } },
+        ],
+    };
+};
+/**
+ * Phase 5.5b — c15:funnelChart body. Categories label each funnel
+ * stage; values size the stages. No subtotals, no quartile config.
+ */
+const buildC15FunnelChartNode = (_spec, seriesRefs, series, domainRef, axIds) => {
+    const c15SeriesEntries = [];
+    seriesRefs.forEach((ref, index) => {
+        if (!ref)
+            return;
+        const seriesNode = {
+            "c15:idx": { a$: { val: String(index) } },
+            "c15:order": { a$: { val: String(index) } },
+        };
+        const dataLabel = series[index]?.dataLabel;
+        if (dataLabel && !dataLabel.startsWith("=")) {
+            seriesNode["c15:tx"] = { "c15:v": dataLabel };
+        }
+        if (domainRef) {
+            seriesNode["c15:cat"] = {
+                "c15:strRef": { "c15:f": domainRef },
+            };
+        }
+        seriesNode["c15:val"] = {
+            "c15:numRef": { "c15:f": ref },
+        };
+        c15SeriesEntries.push(seriesNode);
+    });
+    return {
+        "c15:varyColors": { a$: { val: "0" } },
+        "c15:ser": c15SeriesEntries.length === 1 ? c15SeriesEntries[0] : c15SeriesEntries,
+        "c15:axId": [
+            { a$: { val: axIds.catAxId } },
+            { a$: { val: axIds.valAxId } },
+        ],
+    };
+};
+/**
+ * Phase 5.5b — wrap a c15 chart body in `mc:AlternateContent` so Excel
+ * 2016+ uses the c15 chart and older Excel falls back to the bar chart.
+ * Returns the AlternateContent node ready to splice into c:plotArea.
+ */
+const buildC15AlternateContent = (chartType, c15ChartBody, fallbackBarChart) => {
+    const choiceElementName = C15_ELEMENT_NAMES[chartType];
+    return {
+        a$: { "xmlns:mc": MC_NS },
+        "mc:Choice": {
+            a$: {
+                Requires: "c15",
+                "xmlns:c15": C15_NS,
+            },
+            [choiceElementName]: c15ChartBody,
+        },
+        "mc:Fallback": {
+            "c:barChart": fallbackBarChart,
+        },
+    };
+};
+/**
+ * Group series by their effective chart type for combo chart support.
+ * Returns a map of chart type to array of {index, ref, seriesData}.
+ */
+const groupSeriesByChartType = (series, seriesRefs, defaultChartType) => {
+    const groups = new Map();
+    seriesRefs.forEach((ref, index) => {
+        if (!ref)
+            return;
+        const seriesData = series[index];
+        const effectiveType = (seriesData?.seriesChartType ?? defaultChartType);
+        if (!groups.has(effectiveType)) {
+            groups.set(effectiveType, []);
+        }
+        groups.get(effectiveType).push({ index, ref, data: seriesData });
+    });
+    return groups;
+};
+/**
+ * Check if a chart has multiple series types (combo chart).
+ */
+const isComboChart = (series, defaultChartType) => {
+    const types = new Set();
+    for (const s of series) {
+        types.add(s.seriesChartType ?? defaultChartType);
+    }
+    return types.size > 1;
+};
+/**
+ * Build a bar/column series node.
+ */
+const buildBarSeriesNode = (index, ref, seriesData, domainRef, sheetName, isFirstInGroup) => {
+    const seriesNode = cloneTemplate(column_series);
+    seriesNode["c:idx"] = { a$: { val: index.toString() } };
+    seriesNode["c:order"] = { a$: { val: index.toString() } };
+    const seriesColor = seriesData?.color;
+    const anyData = seriesData;
+    // noFill takes precedence over any other fill — Gantt-style
+    // invisible offset series. Must run BEFORE solidFill/gradient so it
+    // can wipe the template's default fill.
+    if (anyData?.noFill) {
+        applyNoFillToSeriesSpPr(seriesNode);
+    }
+    else if (applySeriesGradient(seriesNode, seriesData?.gradient)) {
+        // Gradient wins — solid/scheme already cleared.
+    }
+    else if (seriesColor) {
+        seriesNode["c:spPr"]["a:solidFill"] =
+            buildColorNode(seriesColor)["a:solidFill"];
+    }
+    else if (index < 6) {
+        seriesNode["c:spPr"]["a:solidFill"]["a:schemeClr"].a$.val = `accent${index + 1}`;
+    }
+    // Per-data-point colors — emit `<c:dPt>` array after the series-
+    // level fill. Each entry overrides the fill for one category index.
+    const dPtNodes = buildDataPointNodes(anyData?.dataPointColors);
+    if (dPtNodes) {
+        seriesNode["c:dPt"] = dPtNodes;
+    }
+    // Handle invertIfNegative for negative bar coloring
+    const invertIfNegative = seriesData?.invertIfNegative;
+    const negativeColor = seriesData?.negativeColor;
+    if (invertIfNegative) {
+        seriesNode["c:invertIfNegative"] = { a$: { val: "1" } };
+        const uniqueId = `{${crypto.randomUUID().toUpperCase()}}`;
+        seriesNode["c:extLst"] = buildSeriesExtLst(negativeColor ?? undefined, uniqueId);
+    }
+    // Excel writes the category reference on every series, not just the first
+    // in a group — readers treat a cat-less series as having no categories.
+    if (domainRef) {
+        seriesNode["c:cat"] = {
+            "c:strRef": {
+                "c:f": domainRef,
+            },
+        };
+    }
+    else if (seriesData?.inlineDomainValues) {
+        // Inline category labels (`<c:strLit>`) — used when categories are
+        // embedded in the chart XML rather than from a sheet range.
+        seriesNode["c:cat"] = buildInlineStrLit(seriesData.inlineDomainValues);
+    }
+    seriesNode["c:val"]["c:numRef"]["c:f"] = ref;
+    // Inline series values (`<c:numLit>`) — when the series carries its
+    // own values rather than a cell-range. Rare for bars but valid.
+    const inlineValues = anyData?.inlineValues;
+    if (!ref && Array.isArray(inlineValues) && inlineValues.length) {
+        removeProp(seriesNode, "c:val");
+        seriesNode["c:val"] = buildInlineNumLit(inlineValues);
+    }
+    const labelNode = buildSeriesLabel(seriesData?.dataLabel ?? undefined, sheetName, seriesData?.dataLabelRef);
+    if (labelNode) {
+        seriesNode["c:tx"] = labelNode["c:tx"];
+    }
+    // Per-series marker — typically scatter/bubble but bar/line/area
+    // charts can carry one too via `<c:marker>`.
+    const markerNode = buildMarkerNode(anyData?.marker);
+    if (markerNode) {
+        seriesNode["c:marker"] = markerNode;
+    }
+    return seriesNode;
+};
+/**
+ * Build a line series node.
+ */
+const buildLineSeriesNode = (index, ref, seriesData, domainRef, sheetName, smooth) => {
+    const seriesNode = cloneTemplate(line_series);
+    seriesNode["c:idx"] = { a$: { val: index.toString() } };
+    seriesNode["c:order"] = { a$: { val: index.toString() } };
+    const seriesColor = seriesData?.color;
+    // Line series carry the stroke fill on `c:spPr/a:ln`. A gradient on
+    // a line stroke is unusual (Excel renders a flat-color stroke even
+    // when the underlying spec carries a gradient on `a:ln`), so we
+    // prefer a solid stroke and only apply the gradient to the bg-style
+    // `c:spPr/a:solidFill` slot when present. If the caller explicitly
+    // requested a gradient, we replace the stroke's solid color with
+    // the first stop's hex — best-effort fallback.
+    if (seriesData?.gradient && seriesData.gradient.stops?.length) {
+        const first = seriesData.gradient.stops[0].color;
+        seriesNode["c:spPr"]["a:ln"]["a:solidFill"] =
+            buildColorNode(first)["a:solidFill"];
+    }
+    else if (seriesColor) {
+        seriesNode["c:spPr"]["a:ln"]["a:solidFill"] =
+            buildColorNode(seriesColor)["a:solidFill"];
+    }
+    else if (index < 6) {
+        seriesNode["c:spPr"]["a:ln"]["a:solidFill"]["a:schemeClr"].a$.val = `accent${index + 1}`;
+    }
+    if (domainRef) {
+        seriesNode["c:cat"]["c:strRef"]["c:f"] = domainRef;
+    }
+    else {
+        removeProp(seriesNode, "c:cat");
+    }
+    seriesNode["c:val"]["c:numRef"]["c:f"] = ref;
+    if (smooth) {
+        seriesNode["c:smooth"].a$.val = "1";
+    }
+    const labelNode = buildSeriesLabel(seriesData?.dataLabel ?? undefined, sheetName, seriesData?.dataLabelRef);
+    if (labelNode) {
+        seriesNode["c:tx"] = labelNode["c:tx"];
+    }
+    return seriesNode;
+};
+/**
+ * Build an area series node.
+ */
+const buildAreaSeriesNode = (index, ref, seriesData, domainRef, sheetName) => {
+    const seriesNode = cloneTemplate(area_series);
+    seriesNode["c:idx"] = { a$: { val: index.toString() } };
+    seriesNode["c:order"] = { a$: { val: index.toString() } };
+    const seriesColor = seriesData?.color;
+    if (applySeriesGradient(seriesNode, seriesData?.gradient)) {
+        // Gradient applied to the fill area. Stroke stays solid using
+        // the first stop's color so the outline is visible.
+        if (seriesData?.gradient?.stops?.length) {
+            seriesNode["c:spPr"]["a:ln"]["a:solidFill"] =
+                buildColorNode(seriesData.gradient.stops[0].color)["a:solidFill"];
+        }
+    }
+    else if (seriesColor) {
+        seriesNode["c:spPr"]["a:solidFill"] =
+            buildColorNode(seriesColor)["a:solidFill"];
+        seriesNode["c:spPr"]["a:ln"]["a:solidFill"] =
+            buildColorNode(seriesColor)["a:solidFill"];
+    }
+    else if (index < 6) {
+        seriesNode["c:spPr"]["a:solidFill"]["a:schemeClr"].a$.val = `accent${index + 1}`;
+        seriesNode["c:spPr"]["a:ln"]["a:solidFill"]["a:schemeClr"].a$.val = `accent${index + 1}`;
+    }
+    if (domainRef) {
+        seriesNode["c:cat"]["c:strRef"]["c:f"] = domainRef;
+    }
+    else {
+        removeProp(seriesNode, "c:cat");
+    }
+    seriesNode["c:val"]["c:numRef"]["c:f"] = ref;
+    const labelNode = buildSeriesLabel(seriesData?.dataLabel ?? undefined, sheetName, seriesData?.dataLabelRef);
+    if (labelNode) {
+        seriesNode["c:tx"] = labelNode["c:tx"];
+    }
+    return seriesNode;
+};
+/**
+ * Pie/doughnut templates carry exactly one `c:ser`; a source chart with
+ * several series (e.g. seven single-cell slices) silently lost all but the
+ * first. Convert the template's ser into an array and append one node per
+ * remaining series, each with its own idx/order, name, category and value
+ * reference.
+ */
+const appendExtraCircularSeries = (chartNode, groupKey, seriesRefs, seriesCatRefs, domainRef, series, sheetName) => {
+    const group = chartNode["c:plotArea"]?.[groupKey];
+    if (!group)
+        return;
+    const extra = seriesRefs
+        .map((ref, index) => ({ ref, index }))
+        .filter(({ ref, index }) => index > 0 && Boolean(ref));
+    if (!extra.length)
+        return;
+    const firstSer = group["c:ser"];
+    const sers = Array.isArray(firstSer) ? firstSer : [firstSer];
+    // The template's single ser is series 0; give it its per-series cat when
+    // one was captured.
+    const firstCat = seriesCatRefs[0];
+    if (firstCat && sers[0]?.["c:cat"]?.["c:strRef"]) {
+        sers[0]["c:cat"]["c:strRef"]["c:f"] = firstCat;
+    }
+    for (const { ref, index } of extra) {
+        const node = {
+            "c:idx": { a$: { val: String(index) } },
+            "c:order": { a$: { val: String(index) } },
+        };
+        const labelNode = buildSeriesLabel(series[index]?.dataLabel ?? undefined, sheetName, series[index]?.dataLabelRef);
+        if (labelNode) {
+            node["c:tx"] = labelNode["c:tx"];
+        }
+        const catRef = seriesCatRefs[index] ?? domainRef;
+        if (catRef) {
+            node["c:cat"] = { "c:strRef": { "c:f": catRef } };
+        }
+        node["c:val"] = { "c:numRef": { "c:f": ref } };
+        sers.push(node);
+    }
+    group["c:ser"] = sers;
+};
+const buildPieChart = (domainRef, valueRef, title, subtitle) => {
+    const pieChart = cloneTemplate(donut_json);
+    applyChartTitle(pieChart, title, undefined, subtitle);
+    const plotArea = pieChart["c:plotArea"];
+    const donut = plotArea["c:doughnutChart"];
+    removeProp(donut, "c:holeSize");
+    plotArea["c:pieChart"] = donut;
+    removeProp(plotArea, "c:doughnutChart");
+    const seriesNode = plotArea["c:pieChart"]["c:ser"];
+    if (domainRef) {
+        seriesNode["c:cat"]["c:strRef"]["c:f"] = domainRef;
+    }
+    if (valueRef) {
+        seriesNode["c:val"]["c:numRef"]["c:f"] = valueRef;
+    }
+    return pieChart;
+};
+/**
+ * Pie-of-pie / bar-of-pie (`<c:ofPieChart>`). Reuses the donut template
+ * like buildPieChart but rebuilds the chart-group node so the of-pie
+ * elements land in the CT_OfPieChart sequence order: ofPieType,
+ * varyColors, ser, dLbls, gapWidth, splitType, splitPos, secondPieSize,
+ * serLines. splitType maps the spec vocabulary back to the OOXML
+ * tokens (`pos`/`val`/`percent`); `<c:serLines/>` turns on Excel's
+ * connector lines between the two plots.
+ */
+const buildOfPieChart = (domainRef, valueRef, title, spec, subtitle) => {
+    const chartObj = cloneTemplate(donut_json);
+    applyChartTitle(chartObj, title, undefined, subtitle);
+    const plotArea = chartObj["c:plotArea"];
+    const donut = plotArea["c:doughnutChart"];
+    // holeSize and firstSliceAng are pie/doughnut-only — invalid inside
+    // <c:ofPieChart>.
+    removeProp(donut, "c:holeSize");
+    removeProp(donut, "c:firstSliceAng");
+    const splitTypeVal = spec?.splitType === "position"
+        ? "pos"
+        : spec?.splitType === "value"
+            ? "val"
+            : spec?.splitType === "percent"
+                ? "percent"
+                : undefined;
+    const ofPieNode = {
+        "c:ofPieType": { a$: { val: spec?.ofPieType === "bar" ? "bar" : "pie" } },
+        "c:varyColors": donut["c:varyColors"],
+        "c:ser": donut["c:ser"],
+        "c:dLbls": donut["c:dLbls"],
+        // Excel's default gap between the two plots.
+        "c:gapWidth": { a$: { val: "100" } },
+        ...(splitTypeVal ? { "c:splitType": { a$: { val: splitTypeVal } } } : {}),
+        ...(typeof spec?.splitPos === "number" && Number.isFinite(spec.splitPos)
+            ? { "c:splitPos": { a$: { val: String(spec.splitPos) } } }
+            : {}),
+        ...(typeof spec?.secondPieSize === "number" &&
+            Number.isFinite(spec.secondPieSize)
+            ? { "c:secondPieSize": { a$: { val: String(Math.round(spec.secondPieSize)) } } }
+            : {}),
+        "c:serLines": {},
+    };
+    plotArea["c:ofPieChart"] = ofPieNode;
+    removeProp(plotArea, "c:doughnutChart");
+    const seriesNode = ofPieNode["c:ser"];
+    if (domainRef) {
+        seriesNode["c:cat"]["c:strRef"]["c:f"] = domainRef;
+    }
+    if (valueRef) {
+        seriesNode["c:val"]["c:numRef"]["c:f"] = valueRef;
+    }
+    return chartObj;
+};
+/**
+ * Minimal builder for chart types that follow the line-style template
+ * (radar, stock, etc.) — single chart-type container with a flat series
+ * list. Reuses the column template and rewrites its barChart block to
+ * the target chart-type element. The renderer/Excel handles the rest.
+ */
+const buildRadarLikeChart = (chartElementKey, domainRef, seriesRefs, title, radarStyle, subtitle) => {
+    const chartObj = cloneTemplate(column_json);
+    applyChartTitle(chartObj, title, undefined, subtitle);
+    const plotArea = chartObj["c:plotArea"];
+    const barChart = plotArea["c:barChart"];
+    const axisIds = barChart?.["c:axId"] ?? [];
+    const containerNode = {
+        "c:varyColors": { a$: { val: "0" } },
+        "c:ser": [],
+        "c:axId": axisIds,
+    };
+    if (chartElementKey === "c:radarChart") {
+        containerNode["c:radarStyle"] = {
+            a$: { val: radarStyle ?? "standard" },
+        };
+    }
+    removeProp(plotArea, "c:barChart");
+    plotArea[chartElementKey] = containerNode;
+    const seriesContainer = containerNode["c:ser"];
+    seriesRefs.forEach((ref, index) => {
+        if (!ref)
+            return;
+        const seriesNode = {
+            "c:idx": { a$: { val: String(index) } },
+            "c:order": { a$: { val: String(index) } },
+            "c:cat": domainRef
+                ? { "c:strRef": { "c:f": domainRef } }
+                : undefined,
+            "c:val": { "c:numRef": { "c:f": ref } },
+        };
+        if (!domainRef)
+            delete seriesNode["c:cat"];
+        seriesContainer.push(seriesNode);
+    });
+    return chartObj;
+};
+const buildDoughnutChart = (domainRef, valueRef, title, subtitle) => {
+    // Doughnut uses the same donut_json template as pie but keeps the
+    // <c:doughnutChart> wrapper (and the holeSize, which we set later
+    // via applyDoughnutHole when the spec carries one).
+    const chartObj = cloneTemplate(donut_json);
+    applyChartTitle(chartObj, title, undefined, subtitle);
+    const plotArea = chartObj["c:plotArea"];
+    const seriesNode = plotArea["c:doughnutChart"]["c:ser"];
+    if (domainRef) {
+        seriesNode["c:cat"]["c:strRef"]["c:f"] = domainRef;
+    }
+    if (valueRef) {
+        seriesNode["c:val"]["c:numRef"]["c:f"] = valueRef;
+    }
+    return chartObj;
+};
+export const buildChartXml = (chart, sheetNameById) => {
+    const series = chart.spec?.series ?? [];
+    if (!series.length)
+        return undefined;
+    const domainRef = formatSourcesRef(chart.spec.domains?.[0]?.sources, sheetNameById);
+    const seriesRefs = series.map((entry) => formatSourcesRef(entry?.sources, sheetNameById));
+    const seriesCatRefs = series.map((entry) => seriesCategoryRef(entry, sheetNameById));
+    if (!seriesRefs.some(Boolean))
+        return undefined;
+    const chartType = chart.spec.chartType;
+    const chartTitle = chart.spec.title ?? undefined;
+    // Subtitle line rendered under the title (e.g. a "Total Value to
+    // Paid-In" caption under "Net MOIC by Fund Vintage"). Emitted as a
+    // second `<a:p>` in the title's rich block — see `applyChartTitle`.
+    const chartSubtitle = chart.spec.subtitle ?? undefined;
+    // Authored title text formatting (color/font/bold) — round-tripped
+    // back so Excel keeps the styled title we read on import.
+    const chartTitleFmt = chart.spec.titleTextFormat ?? undefined;
+    const smooth = "smooth" in chart.spec ? chart.spec.smooth : undefined;
+    const chartSpace = cloneTemplate(chart_template);
+    const sheetName = sheetNameById.get(chart.position.sheetId);
+    // Check for combo chart (multiple series chart types)
+    if (isComboChart(series, chartType)) {
+        const groups = groupSeriesByChartType(series, seriesRefs, chartType);
+        // Build combo chart with multiple chart type containers
+        const comboChart = cloneTemplate(column_json);
+        applyChartTitle(comboChart, chartTitle, chartTitleFmt, chartSubtitle);
+        const plotArea = comboChart["c:plotArea"];
+        const baseBarChart = plotArea["c:barChart"];
+        const axisIds = baseBarChart?.["c:axId"] ?? [];
+        const dLbls = baseBarChart?.["c:dLbls"] ?? {};
+        // Remove the default bar chart - we'll add specific chart types
+        removeProp(plotArea, "c:barChart");
+        // Add chart type containers for each group
+        for (const [groupType, groupSeries] of groups) {
+            if (groupType === "bar" || groupType === "column") {
+                const barChartNode = {
+                    "c:barDir": { a$: { val: groupType === "bar" ? "bar" : "col" } },
+                    "c:grouping": { a$: { val: "clustered" } },
+                    "c:varyColors": { a$: { val: "0" } },
+                    "c:ser": [],
+                    "c:dLbls": dLbls,
+                    "c:axId": axisIds,
+                };
+                for (let i = 0; i < groupSeries.length; i++) {
+                    const { index, ref, data } = groupSeries[i];
+                    const seriesNode = buildBarSeriesNode(index, ref, data, seriesCatRefs[index] ?? domainRef, sheetName, i === 0);
+                    barChartNode["c:ser"].push(seriesNode);
+                }
+                plotArea["c:barChart"] = barChartNode;
+            }
+            else if (groupType === "line") {
+                const lineChartNode = {
+                    "c:grouping": { a$: { val: "standard" } },
+                    "c:varyColors": { a$: { val: "0" } },
+                    "c:ser": [],
+                    "c:dLbls": dLbls,
+                    "c:axId": axisIds,
+                };
+                for (const { index, ref, data } of groupSeries) {
+                    const seriesNode = buildLineSeriesNode(index, ref, data, seriesCatRefs[index] ?? domainRef, sheetName, smooth);
+                    lineChartNode["c:ser"].push(seriesNode);
+                }
+                plotArea["c:lineChart"] = lineChartNode;
+            }
+            else if (groupType === "area") {
+                const areaChartNode = {
+                    "c:grouping": { a$: { val: "standard" } },
+                    "c:varyColors": { a$: { val: "0" } },
+                    "c:ser": [],
+                    "c:dLbls": dLbls,
+                    "c:axId": axisIds,
+                };
+                for (const { index, ref, data } of groupSeries) {
+                    const seriesNode = buildAreaSeriesNode(index, ref, data, seriesCatRefs[index] ?? domainRef, sheetName);
+                    areaChartNode["c:ser"].push(seriesNode);
+                }
+                plotArea["c:areaChart"] = areaChartNode;
+            }
+        }
+        chartSpace["c:chartSpace"]["c:chart"] = comboChart;
+        const xml = chartBuilder.build(chartSpace);
+        return `${XML_DECLARATION}${xml}`;
+    }
+    // Handle non-combo charts (original logic)
+    if (isC15ChartType(chartType)) {
+        // Histogram / boxplot / waterfall / funnel emit as a barChart for
+        // older Excel compatibility. For histogram (Phase 5.5b), the
+        // barChart is wrapped in mc:AlternateContent with a c15:histogramChart
+        // sibling in mc:Choice — Excel 2016+ uses the c15 chart, older
+        // versions fall back to bar. For boxplot/waterfall/funnel we still
+        // use the c15 extension marker (round-trips in our pipeline; opens
+        // as bar chart in Excel) until those types get the same upgrade.
+        const barChartDoc = cloneTemplate(column_json);
+        applyChartTitle(barChartDoc, chartTitle, chartTitleFmt, chartSubtitle);
+        const bar = barChartDoc["c:plotArea"]["c:barChart"];
+        bar["c:barDir"].a$.val = "col";
+        const seriesContainer = bar["c:ser"];
+        seriesRefs.forEach((ref, index) => {
+            if (!ref)
+                return;
+            const seriesNode = cloneTemplate(column_series);
+            seriesNode["c:idx"] = { a$: { val: index.toString() } };
+            seriesNode["c:order"] = { a$: { val: index.toString() } };
+            const seriesColor = series[index]?.color;
+            if (applySeriesGradient(seriesNode, series[index]?.gradient)) {
+                // Gradient applied; nothing else.
+            }
+            else if (seriesColor) {
+                seriesNode["c:spPr"]["a:solidFill"] =
+                    buildColorNode(seriesColor)["a:solidFill"];
+            }
+            else if (index < 6) {
+                seriesNode["c:spPr"]["a:solidFill"]["a:schemeClr"].a$.val = `accent${index + 1}`;
+            }
+            if (!index && domainRef) {
+                seriesNode["c:cat"] = {
+                    "c:strRef": {
+                        "c:f": domainRef,
+                    },
+                };
+            }
+            seriesNode["c:val"]["c:numRef"]["c:f"] = ref;
+            const labelNode = buildSeriesLabel(series[index]?.dataLabel ?? undefined, sheetNameById.get(chart.position.sheetId), series[index]?.dataLabelRef);
+            if (labelNode) {
+                seriesNode["c:tx"] = labelNode["c:tx"];
+            }
+            seriesContainer.push(seriesNode);
+        });
+        // Phase 5.5b: wrap the bar chart in mc:AlternateContent and emit
+        // a full c15:* chart in mc:Choice so Excel 2016+ renders natively.
+        // c:catAx / c:valAx stay at c:plotArea level — both Choice and
+        // Fallback reference them through matching axId values.
+        const axIdNodes = bar["c:axId"];
+        const catAxId = axIdNodes?.[0]?.a$?.val ?? "1";
+        const valAxId = axIdNodes?.[1]?.a$?.val ?? "2";
+        const c15Args = {
+            seriesRefs,
+            series,
+            domainRef,
+            axIds: { catAxId, valAxId },
+        };
+        let c15Chart;
+        if (chartType === "histogram") {
+            c15Chart = buildC15HistogramChartNode(chart.spec, c15Args.seriesRefs, c15Args.series, c15Args.domainRef, c15Args.axIds);
+        }
+        else if (chartType === "boxplot") {
+            c15Chart = buildC15BoxplotChartNode(chart.spec, c15Args.seriesRefs, c15Args.series, c15Args.domainRef, c15Args.axIds);
+        }
+        else if (chartType === "waterfall") {
+            c15Chart = buildC15WaterfallChartNode(chart.spec, c15Args.seriesRefs, c15Args.series, c15Args.domainRef, c15Args.axIds);
+        }
+        else {
+            c15Chart = buildC15FunnelChartNode(chart.spec, c15Args.seriesRefs, c15Args.series, c15Args.domainRef, c15Args.axIds);
+        }
+        const altContent = buildC15AlternateContent(chartType, c15Chart, bar);
+        removeProp(barChartDoc["c:plotArea"], "c:barChart");
+        barChartDoc["c:plotArea"]["mc:AlternateContent"] = altContent;
+        chartSpace["c:chartSpace"]["c:chart"] = barChartDoc;
+    }
+    else if (chartType === "bar" || chartType === "column") {
+        const barChart = cloneTemplate(column_json);
+        applyChartTitle(barChart, chartTitle, chartTitleFmt, chartSubtitle);
+        const bar = barChart["c:plotArea"]["c:barChart"];
+        bar["c:barDir"].a$.val = chartType === "bar" ? "bar" : "col";
+        // Grouping / overlap / gapWidth — Excel's stacked / percent-stacked
+        // bars need these set. Excel's defaults are `clustered` + overlap=0
+        // + gapWidth=150; we only emit when the spec actually carries a
+        // value to avoid bloating the file.
+        const stackedType = chart.spec.stackedType;
+        if (stackedType === "STACKED") {
+            bar["c:grouping"] = { a$: { val: "stacked" } };
+        }
+        else if (stackedType === "PERCENT_STACKED") {
+            bar["c:grouping"] = { a$: { val: "percentStacked" } };
+        }
+        else if (stackedType === "UNSTACKED") {
+            bar["c:grouping"] = { a$: { val: "clustered" } };
+        }
+        const overlap = chart.spec.overlap;
+        if (typeof overlap === "number") {
+            bar["c:overlap"] = { a$: { val: String(Math.round(overlap)) } };
+        }
+        const gapWidth = chart.spec.gapWidth;
+        if (typeof gapWidth === "number") {
+            bar["c:gapWidth"] = { a$: { val: String(Math.round(gapWidth)) } };
+        }
+        const seriesContainer = bar["c:ser"];
+        // Inline categories — when no cell-range, use the first domain's
+        // inlineValues directly on the first series' c:cat.
+        const inlineDomainValues = chart.spec.domains?.[0]
+            ?.inlineValues;
+        seriesRefs.forEach((ref, index) => {
+            if (!ref && !series[index]?.inlineValues)
+                return;
+            // Decorate the spec entry with the chart-level inline domain so
+            // `buildBarSeriesNode` can emit `<c:strLit>` on the first series.
+            const enrichedSeries = index === 0 && !domainRef && inlineDomainValues?.length
+                ? {
+                    ...series[index],
+                    inlineDomainValues,
+                }
+                : series[index];
+            const seriesNode = buildBarSeriesNode(index, ref ?? "", enrichedSeries, seriesCatRefs[index] ?? domainRef, sheetNameById.get(chart.position.sheetId), index === 0);
+            seriesContainer.push(seriesNode);
+        });
+        chartSpace["c:chartSpace"]["c:chart"] = barChart;
+    }
+    else if (chartType === "pie") {
+        const valueRef = seriesRefs.find(Boolean);
+        const specAny = chart.spec;
+        // Pie-of-pie / bar-of-pie round-trips as <c:ofPieChart> when the
+        // spec carries the OF_PIE marker (or an explicit ofPieType).
+        const isOfPie = String(specAny?.sourceChartType ?? "").toUpperCase() === "OF_PIE" ||
+            specAny?.ofPieType === "pie" ||
+            specAny?.ofPieType === "bar";
+        const pieChart = isOfPie
+            ? buildOfPieChart(domainRef, valueRef, chartTitle, specAny, chartSubtitle)
+            : buildPieChart(domainRef, valueRef, chartTitle, chartSubtitle);
+        if (!isOfPie) {
+            appendExtraCircularSeries(pieChart, "c:pieChart", seriesRefs, seriesCatRefs, domainRef, series, sheetNameById.get(chart.position.sheetId));
+        }
+        chartSpace["c:chartSpace"]["c:chart"] = pieChart;
+    }
+    else if (chartType === "doughnut") {
+        const valueRef = seriesRefs.find(Boolean);
+        const doughnutChart = buildDoughnutChart(domainRef, valueRef, chartTitle, chartSubtitle);
+        appendExtraCircularSeries(doughnutChart, "c:doughnutChart", seriesRefs, seriesCatRefs, domainRef, series, sheetNameById.get(chart.position.sheetId));
+        chartSpace["c:chartSpace"]["c:chart"] = doughnutChart;
+    }
+    else if (chartType === "radar") {
+        const radarChart = buildRadarLikeChart("c:radarChart", domainRef, seriesRefs, chartTitle, chart.spec.radarStyle ?? "standard", chartSubtitle);
+        chartSpace["c:chartSpace"]["c:chart"] = radarChart;
+    }
+    else if (chartType === "stock") {
+        const stockChart = buildRadarLikeChart("c:stockChart", domainRef, seriesRefs, chartTitle, undefined, chartSubtitle);
+        chartSpace["c:chartSpace"]["c:chart"] = stockChart;
+    }
+    else if (chartType === "line") {
+        const lineChart = cloneTemplate(column_json);
+        applyChartTitle(lineChart, chartTitle, chartTitleFmt, chartSubtitle);
+        const plotArea = lineChart["c:plotArea"];
+        const barChart = plotArea["c:barChart"];
+        const lineChartNode = {
+            "c:grouping": {
+                a$: {
+                    val: "standard",
+                },
+            },
+            "c:varyColors": {
+                a$: {
+                    val: "0",
+                },
+            },
+            "c:ser": [],
+            "c:dLbls": barChart?.["c:dLbls"] ?? {},
+            "c:axId": barChart?.["c:axId"] ?? [],
+        };
+        removeProp(plotArea, "c:barChart");
+        plotArea["c:lineChart"] = lineChartNode;
+        const seriesContainer = lineChartNode["c:ser"];
+        seriesRefs.forEach((ref, index) => {
+            if (!ref)
+                return;
+            const seriesNode = cloneTemplate(line_series);
+            seriesNode["c:idx"] = { a$: { val: index.toString() } };
+            seriesNode["c:order"] = { a$: { val: index.toString() } };
+            const seriesColor = series[index]?.color;
+            if (seriesColor) {
+                seriesNode["c:spPr"]["a:ln"]["a:solidFill"] =
+                    buildColorNode(seriesColor)["a:solidFill"];
+            }
+            else if (index < 6) {
+                seriesNode["c:spPr"]["a:ln"]["a:solidFill"]["a:schemeClr"].a$.val = `accent${index + 1}`;
+            }
+            // Category axis is optional - Excel will use numeric indices if not provided
+            const catRef = seriesCatRefs[index] ?? domainRef;
+            if (catRef) {
+                seriesNode["c:cat"]["c:strRef"]["c:f"] = catRef;
+            }
+            else {
+                // Remove the category reference if no domain
+                removeProp(seriesNode, "c:cat");
+            }
+            seriesNode["c:val"]["c:numRef"]["c:f"] = ref;
+            if (smooth) {
+                seriesNode["c:smooth"].a$.val = "1";
+            }
+            const labelNode = buildSeriesLabel(series[index]?.dataLabel ?? undefined, sheetNameById.get(chart.position.sheetId), series[index]?.dataLabelRef);
+            if (labelNode) {
+                seriesNode["c:tx"] = labelNode["c:tx"];
+            }
+            seriesContainer.push(seriesNode);
+        });
+        chartSpace["c:chartSpace"]["c:chart"] = lineChart;
+    }
+    else if (chartType === "area") {
+        const areaChart = cloneTemplate(column_json);
+        applyChartTitle(areaChart, chartTitle, chartTitleFmt, chartSubtitle);
+        const plotArea = areaChart["c:plotArea"];
+        const barChart = plotArea["c:barChart"];
+        const areaChartNode = {
+            "c:grouping": {
+                a$: {
+                    val: "standard",
+                },
+            },
+            "c:varyColors": {
+                a$: {
+                    val: "0",
+                },
+            },
+            "c:ser": [],
+            "c:dLbls": barChart?.["c:dLbls"] ?? {},
+            "c:axId": barChart?.["c:axId"] ?? [],
+        };
+        removeProp(plotArea, "c:barChart");
+        plotArea["c:areaChart"] = areaChartNode;
+        const seriesContainer = areaChartNode["c:ser"];
+        seriesRefs.forEach((ref, index) => {
+            if (!ref)
+                return;
+            const seriesNode = cloneTemplate(area_series);
+            seriesNode["c:idx"] = { a$: { val: index.toString() } };
+            seriesNode["c:order"] = { a$: { val: index.toString() } };
+            const seriesColor = series[index]?.color;
+            if (seriesColor) {
+                seriesNode["c:spPr"]["a:solidFill"] =
+                    buildColorNode(seriesColor)["a:solidFill"];
+                seriesNode["c:spPr"]["a:ln"]["a:solidFill"] =
+                    buildColorNode(seriesColor)["a:solidFill"];
+            }
+            else if (index < 6) {
+                seriesNode["c:spPr"]["a:solidFill"]["a:schemeClr"].a$.val = `accent${index + 1}`;
+                seriesNode["c:spPr"]["a:ln"]["a:solidFill"]["a:schemeClr"].a$.val = `accent${index + 1}`;
+            }
+            // Category axis is optional - Excel will use numeric indices if not provided
+            const catRef = seriesCatRefs[index] ?? domainRef;
+            if (catRef) {
+                seriesNode["c:cat"]["c:strRef"]["c:f"] = catRef;
+            }
+            else {
+                removeProp(seriesNode, "c:cat");
+            }
+            seriesNode["c:val"]["c:numRef"]["c:f"] = ref;
+            const labelNode = buildSeriesLabel(series[index]?.dataLabel ?? undefined, sheetNameById.get(chart.position.sheetId), series[index]?.dataLabelRef);
+            if (labelNode) {
+                seriesNode["c:tx"] = labelNode["c:tx"];
+            }
+            seriesContainer.push(seriesNode);
+        });
+        chartSpace["c:chartSpace"]["c:chart"] = areaChart;
+    }
+    else if (chartType === "scatter" || chartType === "bubble") {
+        const bubbleSpec = chart.spec;
+        const domainEntries = bubbleSpec.domains ?? [];
+        const seriesEntries = bubbleSpec.series ?? [];
+        const bubbleSizeEntries = bubbleSpec.bubbleSizes ?? [];
+        const bubbleLabelEntries = bubbleSpec.bubbleLabels ?? [];
+        const seriesContainer = [];
+        const seriesTemplate = chartType === "bubble" ? bubble_series : scatter_series;
+        seriesEntries.forEach((entry, index) => {
+            const domainRef = formatRangeRef(getPrimarySource(domainEntries[index]) ??
+                getPrimarySource(domainEntries[0]), sheetNameById);
+            const valueRef = formatRangeRef(getPrimarySource(entry), sheetNameById);
+            if (!domainRef || !valueRef)
+                return;
+            const seriesNode = cloneTemplate(seriesTemplate);
+            seriesNode["c:idx"] = { a$: { val: index.toString() } };
+            seriesNode["c:order"] = { a$: { val: index.toString() } };
+            const seriesColor = entry?.color;
+            if (seriesColor) {
+                if (chartType === "bubble") {
+                    seriesNode["c:spPr"]["a:solidFill"] =
+                        buildColorNode(seriesColor)["a:solidFill"];
+                }
+                else {
+                    seriesNode["c:spPr"]["a:ln"]["a:solidFill"] =
+                        buildColorNode(seriesColor)["a:solidFill"];
+                }
+            }
+            else if (index < 6) {
+                const colorNode = chartType === "bubble"
+                    ? seriesNode["c:spPr"]["a:solidFill"]["a:schemeClr"]
+                    : seriesNode["c:spPr"]["a:ln"]["a:solidFill"]["a:schemeClr"];
+                colorNode.a$.val = `accent${index + 1}`;
+            }
+            seriesNode["c:xVal"]["c:numRef"]["c:f"] = domainRef;
+            seriesNode["c:yVal"]["c:numRef"]["c:f"] = valueRef;
+            if (chartType === "bubble") {
+                const sizeRef = formatRangeRef(getPrimarySource(bubbleSizeEntries[index]) ??
+                    getPrimarySource(bubbleSizeEntries[0]) ??
+                    getPrimarySource(entry), sheetNameById);
+                if (sizeRef) {
+                    seriesNode["c:bubbleSize"]["c:numRef"]["c:f"] = sizeRef;
+                }
+            }
+            else if (smooth) {
+                seriesNode["c:smooth"].a$.val = "1";
+            }
+            const labelNode = buildSeriesLabel(entry?.dataLabel ?? bubbleLabelEntries[index]?.dataLabel ?? undefined, sheetNameById.get(chart.position.sheetId), entry?.dataLabelRef);
+            if (labelNode) {
+                seriesNode["c:tx"] = labelNode["c:tx"];
+            }
+            seriesContainer.push(seriesNode);
+        });
+        if (!seriesContainer.length)
+            return undefined;
+        const chartDoc = cloneTemplate(scatter_json);
+        applyChartTitle(chartDoc, chartTitle, chartTitleFmt, chartSubtitle);
+        const plotArea = chartDoc["c:plotArea"];
+        const scatterChart = plotArea["c:scatterChart"];
+        if (chartType === "bubble") {
+            removeProp(plotArea, "c:scatterChart");
+            removeProp(scatterChart, "c:scatterStyle");
+            scatterChart["c:bubbleScale"] = { a$: { val: "100" } };
+            scatterChart["c:showNegBubbles"] = { a$: { val: "0" } };
+            scatterChart["c:sizeRepresents"] = { a$: { val: "area" } };
+            plotArea["c:bubbleChart"] = scatterChart;
+        }
+        else {
+            // <c:scatterStyle> — Excel default is "lineMarker". Round-trip
+            // whatever the spec carries so the connecting line / marker mix
+            // survives re-saving.
+            const scatterStyle = chart.spec.scatterStyle;
+            if (scatterStyle && typeof scatterStyle === "string") {
+                scatterChart["c:scatterStyle"] = { a$: { val: scatterStyle } };
+            }
+        }
+        // Per-series marker — append to each series node that doesn't yet
+        // carry one (scatter/bubble series templates already include a
+        // marker block in many cases; only add when authored).
+        seriesContainer.forEach((node, i) => {
+            const markerSpec = chart.spec.series?.[i]?.marker;
+            const m = buildMarkerNode(markerSpec);
+            if (m) {
+                node["c:marker"] = m;
+            }
+        });
+        const targetChart = chartType === "bubble" ? plotArea["c:bubbleChart"] : scatterChart;
+        targetChart["c:ser"] = seriesContainer;
+        chartSpace["c:chartSpace"]["c:chart"] = chartDoc;
+    }
+    else if (chartType === "treemap" || chartType === "sunburst") {
+        const treeSpec = chart.spec;
+        const labelRef = formatRangeRef(getPrimarySource(treeSpec.labels?.[0]), sheetNameById);
+        const sizeRef = formatRangeRef(getPrimarySource(treeSpec.sizeData?.[0]), sheetNameById);
+        if (!labelRef || !sizeRef)
+            return undefined;
+        if (chartType === "sunburst") {
+            const pieChart = buildPieChart(labelRef, sizeRef, chartTitle, chartSubtitle);
+            chartSpace["c:chartSpace"]["c:chart"] = pieChart;
+        }
+        else {
+            const columnChart = cloneTemplate(column_json);
+            applyChartTitle(columnChart, chartTitle, chartTitleFmt, chartSubtitle);
+            const bar = columnChart["c:plotArea"]["c:barChart"];
+            const seriesContainer = bar["c:ser"];
+            const seriesNode = cloneTemplate(column_series);
+            seriesNode["c:idx"] = { a$: { val: "0" } };
+            seriesNode["c:order"] = { a$: { val: "0" } };
+            seriesNode["c:cat"] = {
+                "c:strRef": {
+                    "c:f": labelRef,
+                },
+            };
+            seriesNode["c:val"]["c:numRef"]["c:f"] = sizeRef;
+            seriesContainer.push(seriesNode);
+            chartSpace["c:chartSpace"]["c:chart"] = columnChart;
+        }
+    }
+    else {
+        return undefined;
+    }
+    // Apply Phase 5.1 formatting (legend, data labels, axis options) to the
+    // assembled chart. These mutate the chart node in place — they're
+    // chartType-agnostic and intentionally run last so per-type branches
+    // don't have to know about them.
+    applyChartFormatting(chartSpace, chart.spec, sheetNameById);
+    // `<c:roundedCorners val="1"/>` lives at the chartSpace root (sibling
+    // of `<c:chart>`). Default per OOXML §21.2.2.183 is `false`; only
+    // emit when the spec opted in so files imported without the element
+    // round-trip cleanly without gaining a spurious one.
+    if (chart.spec.roundedCorners) {
+        chartSpace["c:chartSpace"]["c:roundedCorners"] = { a$: { val: "1" } };
+    }
+    const xml = chartBuilder.build(chartSpace);
+    return `${XML_DECLARATION}${xml}`;
+};
+// -------------------------- Phase 5 helpers --------------------------
+const LEGEND_POS = {
+    top: "t",
+    bottom: "b",
+    left: "l",
+    right: "r",
+    topRight: "tr",
+};
+const DLBL_POS = {
+    center: "ctr",
+    inside: "inBase",
+    outside: "outEnd",
+    insideEnd: "inEnd",
+    outsideEnd: "outEnd",
+    bestFit: "bestFit",
+};
+const applyChartFormatting = (chartSpace, spec, sheetNameById) => {
+    const chartNode = chartSpace?.["c:chartSpace"]?.["c:chart"];
+    if (!chartNode)
+        return;
+    applyLegend(chartNode, spec?.legend);
+    const plotArea = chartNode["c:plotArea"];
+    if (!plotArea)
+        return;
+    applyDataLabels(plotArea, spec?.dataLabels);
+    applyAxisOptions(plotArea, spec?.valueAxisOptions, "value");
+    applyAxisOptions(plotArea, spec?.categoryAxisOptions, "category");
+    applyDoughnutHole(plotArea, spec?.doughnutHoleSize);
+    applySeriesOverlays(plotArea, spec?.series, sheetNameById);
+    applySecondaryAxis(plotArea, spec?.secondaryValueAxisOptions);
+};
+const SERIES_CONTAINER_KEYS = [
+    "c:barChart",
+    "c:lineChart",
+    "c:pieChart",
+    "c:doughnutChart",
+    "c:areaChart",
+    "c:scatterChart",
+    "c:bubbleChart",
+];
+/**
+ * Walk the per-chart-type containers in plotArea and apply trendlines
+ * / errBars to each emitted `<c:ser>`. The series order in spec.series
+ * matches the order emitted by the builder, so we index by position.
+ */
+const applySeriesOverlays = (plotArea, series, sheetNameById) => {
+    if (!Array.isArray(series) || !series.length)
+        return;
+    let seriesIndex = 0;
+    for (const key of SERIES_CONTAINER_KEYS) {
+        const container = plotArea[key];
+        if (!container)
+            continue;
+        const ser = container["c:ser"];
+        if (!ser)
+            continue;
+        const list = Array.isArray(ser) ? ser : [ser];
+        for (const node of list) {
+            const data = series[seriesIndex++];
+            if (!data)
+                continue;
+            if (Array.isArray(data.trendlines) && data.trendlines.length) {
+                const built = data.trendlines
+                    .map(buildTrendlineNode)
+                    .filter(Boolean);
+                // OOXML allows multiple <c:trendline> on a series; preserve the
+                // order from the spec.
+                node["c:trendline"] = built.length === 1 ? built[0] : built;
+            }
+            if (data.errorBars) {
+                const built = buildErrorBarsNode(data.errorBars, sheetNameById);
+                if (built)
+                    node["c:errBars"] = built;
+            }
+        }
+    }
+};
+const buildTrendlineNode = (t) => {
+    if (!t)
+        return undefined;
+    const node = {};
+    if (t.name) {
+        node["c:name"] = { t$: String(t.name) };
+    }
+    // <c:trendlineType val="linear|exp|log|poly|power|movingAvg"/>
+    node["c:trendlineType"] = {
+        a$: { val: t.type ?? "linear" },
+    };
+    if (t.type === "poly" && typeof t.order === "number") {
+        node["c:order"] = { a$: { val: String(t.order) } };
+    }
+    if (t.type === "movingAvg" && typeof t.period === "number") {
+        node["c:period"] = { a$: { val: String(t.period) } };
+    }
+    if (typeof t.forecastForward === "number") {
+        node["c:forward"] = { a$: { val: String(t.forecastForward) } };
+    }
+    if (typeof t.forecastBackward === "number") {
+        node["c:backward"] = { a$: { val: String(t.forecastBackward) } };
+    }
+    if (t.showEquation) {
+        node["c:dispEq"] = { a$: { val: "1" } };
+    }
+    if (t.showRSquared) {
+        node["c:dispRSqr"] = { a$: { val: "1" } };
+    }
+    return node;
+};
+const buildErrorBarsNode = (eb, sheetNameById) => {
+    if (!eb)
+        return undefined;
+    const node = {};
+    if (eb.direction === "x" || eb.direction === "y") {
+        node["c:errDir"] = { a$: { val: eb.direction } };
+    }
+    node["c:errBarType"] = { a$: { val: eb.barType ?? "both" } };
+    const valueType = eb.valueType === "custom" ? "cust" : eb.valueType;
+    node["c:errValType"] = { a$: { val: valueType ?? "fixedVal" } };
+    if (eb.noEndCap) {
+        node["c:noEndCap"] = { a$: { val: "1" } };
+    }
+    // Custom error bars — per-point magnitudes come from worksheet
+    // ranges emitted as `<c:plus>/<c:minus>` numRefs. Schema order puts
+    // them after noEndCap and before `<c:val>`.
+    if (valueType === "cust") {
+        const plusRef = formatRangeRef(eb.plusRange ?? undefined, sheetNameById);
+        const minusRef = formatRangeRef(eb.minusRange ?? undefined, sheetNameById);
+        if (plusRef) {
+            node["c:plus"] = { "c:numRef": { "c:f": plusRef } };
+        }
+        if (minusRef) {
+            node["c:minus"] = { "c:numRef": { "c:f": minusRef } };
+        }
+    }
+    if (typeof eb.value === "number") {
+        node["c:val"] = { a$: { val: String(eb.value) } };
+    }
+    return node;
+};
+/**
+ * Add a secondary `<c:valAx>` next to the primary one when the spec
+ * carries `secondaryValueAxisOptions`. We give it a distinct axId
+ * (existing primary axId + 100) — series-level routing to the new axis
+ * is intentionally not wired up here (most consumers of "secondary
+ * axis" only care about the data round-trip; full charting fidelity
+ * lands in a follow-up).
+ */
+const applySecondaryAxis = (plotArea, opts) => {
+    if (!opts)
+        return;
+    const existing = plotArea["c:valAx"];
+    if (!existing)
+        return;
+    const existingArr = Array.isArray(existing) ? existing : [existing];
+    if (existingArr.length >= 2)
+        return; // already has secondary
+    const primary = existingArr[0];
+    const primaryAxId = parseInt((primary?.["c:axId"]?.a$?.val ?? "1000"), 10);
+    const secondary = {
+        "c:axId": { a$: { val: String(primaryAxId + 100) } },
+        "c:scaling": { "c:orientation": { a$: { val: "minMax" } } },
+        "c:delete": { a$: { val: "0" } },
+        "c:axPos": { a$: { val: "r" } },
+        "c:crossAx": { a$: { val: String(primaryAxId) } },
+    };
+    // Apply the same logarithmic / reverse / min / max / gridlines etc.
+    applyAxisOptions({ "c:valAx": secondary }, opts, "value");
+    plotArea["c:valAx"] = [...existingArr, secondary];
+};
+const applyLegend = (chartNode, legend) => {
+    if (!legend)
+        return;
+    if (legend.position === "none") {
+        // Excel omits <c:legend> entirely when hidden; some readers expect
+        // an explicit <c:legend><c:delete val="1"/> instead. Use the
+        // explicit form so the suppression survives ANY reader.
+        chartNode["c:legend"] = {
+            "c:delete": { a$: { val: "1" } },
+        };
+        return;
+    }
+    const posCode = LEGEND_POS[legend.position];
+    const txPr = buildTxPrNode(legend.textFormat);
+    if (!posCode) {
+        // No explicit position — just ensure the legend element exists,
+        // attach text formatting if authored.
+        const existing = chartNode["c:legend"] ?? {};
+        if (txPr)
+            existing["c:txPr"] = txPr;
+        chartNode["c:legend"] = existing;
+        return;
+    }
+    chartNode["c:legend"] = {
+        "c:legendPos": { a$: { val: posCode } },
+        "c:overlay": { a$: { val: "0" } },
+        ...(txPr ? { "c:txPr": txPr } : {}),
+    };
+};
+const applyDataLabels = (plotArea, dataLabels) => {
+    if (!dataLabels?.show)
+        return;
+    // Find the chart-type container inside <c:plotArea>. We attach <c:dLbls>
+    // to whichever exists.
+    const containerKey = [
+        "c:barChart",
+        "c:lineChart",
+        "c:pieChart",
+        "c:doughnutChart",
+        "c:areaChart",
+    ].find((k) => plotArea[k]);
+    if (!containerKey)
+        return;
+    const container = plotArea[containerKey];
+    const posCode = dataLabels.position && DLBL_POS[dataLabels.position];
+    const dLbls = {};
+    if (posCode)
+        dLbls["c:dLblPos"] = { a$: { val: posCode } };
+    // <c:numFmt> — emit before the show* flags. Excel reads this to
+    // format the label value (e.g. `"$"#,##0` → "$1,831").
+    if (dataLabels.numberFormatPattern) {
+        dLbls["c:numFmt"] = {
+            a$: {
+                formatCode: dataLabels.numberFormatPattern,
+                sourceLinked: "0",
+            },
+        };
+    }
+    // <c:txPr> — authored color / font / bold for the label text.
+    const txPr = buildTxPrNode(dataLabels.textFormat);
+    if (txPr)
+        dLbls["c:txPr"] = txPr;
+    // OOXML requires explicit boolean flags. When none of show* are set,
+    // default to showVal=1 since that's Excel's default for "Show Labels".
+    const showValue = dataLabels.showValue === undefined
+        ? !dataLabels.showCategoryName &&
+            !dataLabels.showPercent &&
+            !dataLabels.showSeriesName
+        : !!dataLabels.showValue;
+    dLbls["c:showLegendKey"] = { a$: { val: "0" } };
+    dLbls["c:showVal"] = { a$: { val: showValue ? "1" : "0" } };
+    dLbls["c:showCatName"] = {
+        a$: { val: dataLabels.showCategoryName ? "1" : "0" },
+    };
+    dLbls["c:showSerName"] = {
+        a$: { val: dataLabels.showSeriesName ? "1" : "0" },
+    };
+    dLbls["c:showPercent"] = {
+        a$: { val: dataLabels.showPercent ? "1" : "0" },
+    };
+    dLbls["c:showBubbleSize"] = { a$: { val: "0" } };
+    container["c:dLbls"] = dLbls;
+};
+const applyAxisOptions = (plotArea, options, kind) => {
+    if (!options)
+        return;
+    const axisKey = kind === "value" ? "c:valAx" : "c:catAx";
+    const ax = plotArea[axisKey];
+    if (!ax)
+        return;
+    // OOXML can carry multiple axes (e.g. primary + secondary). Target the
+    // first one for now — secondary axes ship in Phase 5.2.
+    const node = Array.isArray(ax) ? ax[0] : ax;
+    const scaling = (node["c:scaling"] = node["c:scaling"] ?? {});
+    if (options.logarithmic) {
+        scaling["c:logBase"] = { a$: { val: "10" } };
+    }
+    if (options.reverse) {
+        scaling["c:orientation"] = { a$: { val: "maxMin" } };
+    }
+    if (typeof options.min === "number") {
+        scaling["c:min"] = { a$: { val: String(options.min) } };
+    }
+    if (typeof options.max === "number") {
+        scaling["c:max"] = { a$: { val: String(options.max) } };
+    }
+    if (options.visible === false) {
+        node["c:delete"] = { a$: { val: "1" } };
+    }
+    if (options.showMajorGridlines === true && !node["c:majorGridlines"]) {
+        node["c:majorGridlines"] = {};
+    }
+    if (options.showMajorGridlines === false && node["c:majorGridlines"]) {
+        delete node["c:majorGridlines"];
+    }
+    // <c:txPr> — axis tick-label color/font. Without this, exported
+    // axes would render with the default theme color instead of the
+    // authored one (BEP.xlsx axis colors #14325A / #F0621C).
+    const txPr = buildTxPrNode(options.textFormat);
+    if (txPr)
+        node["c:txPr"] = txPr;
+};
+const applyDoughnutHole = (plotArea, holeSize) => {
+    if (typeof holeSize !== "number")
+        return;
+    const doughnut = plotArea["c:doughnutChart"];
+    if (!doughnut)
+        return;
+    // Convert 0-1 fraction back to OOXML's 0-90 percentage.
+    const pct = Math.round(Math.max(0, Math.min(0.9, holeSize)) * 100);
+    doughnut["c:holeSize"] = { a$: { val: String(pct) } };
+};