@rowsncolumns/toolkit 24.4.1

package/dist/esm/excel-parser/plugins/xlsx/charts.js

@@ -0,0 +1,2036 @@
+import { generateSelectionsFromFormula } from "@rowsncolumns/utils";
+import { uuid } from "@rowsncolumns/utils";
+import { get } from "lodash-es";
+/**
+ * Pick the data sheetId for a parsed selection. Honours the explicit
+ * sheet prefix in the chart's formula reference (cross-sheet charts);
+ * falls back to the host sheet when the formula has no prefix.
+ */
+function pickSheetId(sheetName, hostSheetId, resolveSheetId) {
+    if (sheetName && resolveSheetId) {
+        const resolved = resolveSheetId(sheetName);
+        if (resolved !== undefined)
+            return resolved;
+    }
+    return hostSheetId;
+}
+// Import from index.ts in the same directory (circular dependency but resolving symbols)
+// Note: We need to use type import for Workbook if needed, or functions
+// In this case, we need getChartReferenceFromAnchor which was exported from workbook.ts originally
+// but now is in index.ts of the plugin. However, charts.ts doesn't seem to import it based on the file content I read.
+// The search_replace failed because the import wasn't there.
+// Let me double check the file content again.
+// The file content I read has NO imports from "../charts" or "../workbook".
+// It seems I was trying to fix a linter error that I *assumed* existed or was trying to match code that wasn't there.
+// The file content shows standard imports and internal functions.
+function getWithFallback(source, paths) {
+    for (const path of paths) {
+        const value = get(source, path);
+        if (value !== undefined) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function toInt(value) {
+    const parsed = parseInt(typeof value === "number" ? String(value) : value ?? "0", 10);
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+export async function processChart(chartTarget, drawingPath, anchor, sheetId, zipParser, xmlParser, sheetDimensions, resolveSheetId) {
+    try {
+        // Resolve chart file path
+        let chartPath = chartTarget;
+        const drawingDir = drawingPath.substring(0, drawingPath.lastIndexOf("/"));
+        if (chartPath.startsWith("../")) {
+            chartPath = `xl/${chartPath.replace("../", "")}`;
+        }
+        else if (!chartPath.startsWith("/") && !chartPath.startsWith("xl/")) {
+            chartPath = `${drawingDir}/${chartPath}`;
+        }
+        // Read the chart file
+        const chartContent = await zipParser.getText(chartPath);
+        if (!chartContent) {
+            return null;
+        }
+        const chartXml = xmlParser.parse(chartContent);
+        const chart = getWithFallback(chartXml, [
+            "c:chartSpace.c:chart",
+            "chartSpace.chart",
+            "chartSpace.c:chart",
+            "c:chartSpace.chart",
+        ]);
+        if (!chart) {
+            console.log("Chart data not found in file:", chartPath);
+            console.log("Available keys:", Object.keys(chartXml));
+            return null;
+        }
+        // `<c:roundedCorners val="1"/>` is a sibling of `<c:chart>` at the
+        // chartSpace root, not inside `<c:chart>` itself. Default per
+        // OOXML §21.2.2.183 is `false`. Read both namespace-prefixed and
+        // bare forms — fast-xml-parser preserves the namespace when the
+        // schema declares it.
+        const chartSpaceRoot = getWithFallback(chartXml, [
+            "c:chartSpace",
+            "chartSpace",
+        ]);
+        const roundedCornersRaw = getWithFallback(chartSpaceRoot, [
+            "c:roundedCorners",
+            "roundedCorners",
+        ]);
+        const roundedCornersVal = roundedCornersRaw?.a$?.val;
+        const roundedCorners = roundedCornersVal === "1" ||
+            roundedCornersVal === "true" ||
+            roundedCornersVal === true
+            ? true
+            : undefined;
+        const chartId = uuid();
+        // Extract chart title (text + formatting)
+        const title = extractChartTitle(chart);
+        const titleTextFormat = extractChartTitleTextFormat(chart);
+        // Determine chart type
+        const chartType = determineChartType(chart);
+        // Extract data
+        const plotArea = getWithFallback(chart, ["c:plotArea", "plotArea"]);
+        const series = extractChartSeries(plotArea, chartType, sheetId, resolveSheetId);
+        const domains = extractChartDomains(plotArea, chartType, sheetId, resolveSheetId);
+        const dataRange = extractChartDataRange(plotArea, chartType, sheetId, resolveSheetId);
+        // Scatter/bubble only — bubble sizes (3rd dimension) and per-point
+        // labels. Bubble charts also have a `bubble3D` flag that scatter
+        // doesn't carry.
+        const bubbleSizes = chartType === "bubble"
+            ? extractChartBubbleSizes(plotArea, sheetId, resolveSheetId)
+            : undefined;
+        // Scatter only — `<c:scatterStyle val="lineMarker">` etc. controls
+        // whether points are connected and whether markers are drawn.
+        // Excel's default when omitted is "lineMarker".
+        const scatterStyle = chartType === "scatter" ? extractScatterStyle(plotArea) : undefined;
+        // Extract hidden dimension strategy from plotVisOnly
+        const hiddenDimensionStrategy = extractHiddenDimensionStrategy(chart);
+        // Extract position from anchor
+        const position = extractChartPosition(anchor, sheetId, sheetDimensions);
+        if (!position) {
+            console.log("Could not extract chart position");
+            return null;
+        }
+        const legend = extractLegendOptions(chart);
+        const dataLabels = extractDataLabelsOptions(plotArea, chartType);
+        const { valueAxisOptions, secondaryValueAxisOptions, categoryAxisOptions, } = extractAxisOptions(plotArea);
+        const doughnutHoleSize = chartType === "doughnut" ? extractDoughnutHoleSize(plotArea) : undefined;
+        // Pie-of-pie / bar-of-pie — <c:ofPieChart> degrades to chartType
+        // "pie" with sourceChartType "OF_PIE" plus the split fields the
+        // renderer uses to draw the composite layout.
+        const ofPieOptions = chartType === "pie" ? extractOfPieOptions(plotArea) : undefined;
+        const radarStyle = chartType === "radar" ? extractRadarStyle(plotArea) : undefined;
+        const binCount = chartType === "histogram"
+            ? extractC15HistogramBinCount(plotArea)
+            : undefined;
+        // Bar/column-only — <c:grouping>, <c:overlap>, <c:gapWidth>.
+        // Excel encodes percentStacked / stacked / clustered here, and the
+        // overlap/gapWidth shape the bar layout. Without these, the
+        // Event Budget percent-stacked chart renders as clustered.
+        const barLayout = chartType === "bar" || chartType === "column"
+            ? extractBarLayoutOptions(plotArea)
+            : undefined;
+        return {
+            chartId,
+            spec: {
+                title,
+                ...(titleTextFormat ? { titleTextFormat } : {}),
+                chartType,
+                domains,
+                series,
+                dataRange,
+                hiddenDimensionStrategy,
+                // Scatter/bubble must conform to BubbleChartSpec which requires
+                // `bubbleLabels`. We don't currently extract per-point labels
+                // from OOXML (rare in real files); set an empty array so the
+                // renderer's `flattenChartDataValues(spec.bubbleLabels, …)`
+                // call gets a well-formed input.
+                ...(chartType === "scatter" || chartType === "bubble"
+                    ? { bubbleLabels: [] }
+                    : {}),
+                ...(bubbleSizes && bubbleSizes.length ? { bubbleSizes } : {}),
+                ...(scatterStyle
+                    ? { scatterStyle: scatterStyle }
+                    : {}),
+                ...(legend ? { legend } : {}),
+                ...(dataLabels ? { dataLabels } : {}),
+                ...(valueAxisOptions ? { valueAxisOptions } : {}),
+                ...(secondaryValueAxisOptions
+                    ? { secondaryValueAxisOptions }
+                    : {}),
+                ...(categoryAxisOptions ? { categoryAxisOptions } : {}),
+                ...(typeof doughnutHoleSize === "number"
+                    ? { doughnutHoleSize }
+                    : {}),
+                ...(ofPieOptions
+                    ? { sourceChartType: "OF_PIE", ...ofPieOptions }
+                    : {}),
+                ...(radarStyle ? { radarStyle } : {}),
+                ...(typeof binCount === "number" ? { binCount } : {}),
+                ...(barLayout?.stackedType
+                    ? { stackedType: barLayout.stackedType }
+                    : {}),
+                ...(typeof barLayout?.overlap === "number"
+                    ? { overlap: barLayout.overlap }
+                    : {}),
+                ...(typeof barLayout?.gapWidth === "number"
+                    ? { gapWidth: barLayout.gapWidth }
+                    : {}),
+                ...(roundedCorners ? { roundedCorners } : {}),
+            },
+            position,
+            id: chartId,
+            type: "chart",
+        };
+    }
+    catch (err) {
+        console.log("Error processing chart:", err);
+        return null;
+    }
+}
+// Helper to get series elements with namespace fallbacks
+function getSeriesElements(plotArea, chartType) {
+    switch (chartType) {
+        case "bar":
+        case "column":
+        // Phase 5.5 — c15 extension chart types emit a c:barChart body
+        // for older-Excel compatibility, so their series live in the same
+        // place as a bar/column chart. Phase 5.5b — histogram additionally
+        // wraps the barChart in mc:AlternateContent > mc:Fallback, so we
+        // also probe that path.
+        case "histogram":
+        case "boxplot":
+        case "waterfall":
+        case "funnel":
+            return getWithFallback(plotArea, [
+                "c:barChart.c:ser",
+                "barChart.ser",
+                "c:bar3DChart.c:ser",
+                "bar3DChart.ser",
+                "mc:AlternateContent.mc:Fallback.c:barChart.c:ser",
+                "AlternateContent.Fallback.barChart.ser",
+            ]);
+        case "line":
+            return getWithFallback(plotArea, [
+                "c:lineChart.c:ser",
+                "lineChart.ser",
+                "c:line3DChart.c:ser",
+                "line3DChart.ser",
+            ]);
+        case "pie":
+            return getWithFallback(plotArea, [
+                "c:pieChart.c:ser",
+                "pieChart.ser",
+                "c:pie3DChart.c:ser",
+                "pie3DChart.ser",
+                // pie-of-pie / bar-of-pie — determineChartType maps
+                // <c:ofPieChart> to "pie", so its series live here too.
+                "c:ofPieChart.c:ser",
+                "ofPieChart.ser",
+            ]);
+        case "doughnut":
+            return getWithFallback(plotArea, [
+                "c:doughnutChart.c:ser",
+                "doughnutChart.ser",
+            ]);
+        case "area":
+            return getWithFallback(plotArea, [
+                "c:areaChart.c:ser",
+                "areaChart.ser",
+                "c:area3DChart.c:ser",
+                "area3DChart.ser",
+            ]);
+        case "radar":
+            return getWithFallback(plotArea, ["c:radarChart.c:ser", "radarChart.ser"]);
+        case "stock":
+            return getWithFallback(plotArea, ["c:stockChart.c:ser", "stockChart.ser"]);
+        case "scatter":
+            return getWithFallback(plotArea, [
+                "c:scatterChart.c:ser",
+                "scatterChart.ser",
+            ]);
+        case "bubble":
+            return getWithFallback(plotArea, [
+                "c:bubbleChart.c:ser",
+                "bubbleChart.ser",
+            ]);
+        default:
+            return getWithFallback(plotArea, ["c:barChart.c:ser", "barChart.ser"]);
+    }
+}
+// Path tuples used by the per-series ref extractors below. We accept
+// both namespaced and stripped forms because fast-xml-parser is
+// configured both ways in different code paths.
+const X_VAL_REF_PATHS = [
+    "c:xVal.c:numRef.c:f",
+    "c:xVal.c:numRef.c:f.t$",
+    "xVal.numRef.f",
+    "xVal.numRef.f.t$",
+    // scatter X axis can also be string (categorical X)
+    "c:xVal.c:strRef.c:f",
+    "c:xVal.c:strRef.c:f.t$",
+    "xVal.strRef.f",
+    "xVal.strRef.f.t$",
+];
+const Y_VAL_REF_PATHS = [
+    "c:yVal.c:numRef.c:f",
+    "c:yVal.c:numRef.c:f.t$",
+    "yVal.numRef.f",
+    "yVal.numRef.f.t$",
+];
+const BUBBLE_SIZE_REF_PATHS = [
+    "c:bubbleSize.c:numRef.c:f",
+    "c:bubbleSize.c:numRef.c:f.t$",
+    "bubbleSize.numRef.f",
+    "bubbleSize.numRef.f.t$",
+];
+const CAT_REF_PATHS = [
+    "c:cat.c:strRef.c:f",
+    "c:cat.c:numRef.c:f",
+    "c:cat.c:strRef.c:f.t$",
+    "c:cat.c:numRef.c:f.t$",
+    "cat.strRef.f",
+    "cat.numRef.f",
+    "cat.strRef.f.t$",
+    "cat.numRef.f.t$",
+];
+const VAL_REF_PATHS = [
+    "c:val.c:numRef.c:f",
+    "c:val.c:numRef.c:f.t$",
+    "val.numRef.f",
+    "val.numRef.f.t$",
+];
+const TX_REF_PATHS = [
+    "c:tx.c:strRef.c:f",
+    "c:tx.c:strRef.c:f.t$",
+    "tx.strRef.f",
+    "tx.strRef.f.t$",
+];
+const isXYChart = (chartType) => chartType === "scatter" || chartType === "bubble";
+// Extract the overall data range for the chart
+export function extractChartDataRange(plotArea, chartType, sheetId, resolveSheetId) {
+    try {
+        const seriesElements = getSeriesElements(plotArea, chartType);
+        if (!seriesElements)
+            return null;
+        const seriesArray = Array.isArray(seriesElements)
+            ? seriesElements
+            : [seriesElements];
+        // Collect all ranges from the chart, tagged with their parsed
+        // sheet name so cross-sheet refs can be honoured.
+        const allRanges = [];
+        for (const ser of seriesArray) {
+            if (isXYChart(chartType)) {
+                const xRef = getWithFallback(ser, X_VAL_REF_PATHS);
+                const yRef = getWithFallback(ser, Y_VAL_REF_PATHS);
+                const sizeRef = chartType === "bubble"
+                    ? getWithFallback(ser, BUBBLE_SIZE_REF_PATHS)
+                    : undefined;
+                const nameRef = getWithFallback(ser, TX_REF_PATHS);
+                if (xRef)
+                    allRanges.push(xRef);
+                if (yRef)
+                    allRanges.push(yRef);
+                if (sizeRef)
+                    allRanges.push(sizeRef);
+                if (nameRef)
+                    allRanges.push(nameRef);
+            }
+            else {
+                const catRef = getWithFallback(ser, CAT_REF_PATHS);
+                const valRef = getWithFallback(ser, VAL_REF_PATHS);
+                const nameRef = getWithFallback(ser, TX_REF_PATHS);
+                if (catRef)
+                    allRanges.push(catRef);
+                if (valRef)
+                    allRanges.push(valRef);
+                if (nameRef)
+                    allRanges.push(nameRef);
+            }
+        }
+        if (allRanges.length === 0)
+            return null;
+        // Bounding range is computed per-sheet — different ranges may live
+        // on different sheets (a chart referencing both the host sheet and
+        // a data sheet, for example). Per Excel, the chart's "data range"
+        // is logically the union of inputs; we pick the first sheet's
+        // bounding box as the reportable dataRange and pin the rest via
+        // the per-series sources.
+        const boundingRange = calculateBoundingRange(allRanges);
+        if (boundingRange) {
+            const selections = generateSelectionsFromFormula(`=${boundingRange}`);
+            if (selections.length > 0) {
+                const sel = selections[0];
+                const resolved = pickSheetId(sel.sheetName, sheetId, resolveSheetId);
+                return {
+                    ...sel.range,
+                    sheetId: resolved,
+                };
+            }
+        }
+        return null;
+    }
+    catch (err) {
+        console.log("Error extracting chart data range:", err);
+        return null;
+    }
+}
+// Calculate the bounding range that encompasses all the individual ranges
+function calculateBoundingRange(ranges) {
+    try {
+        let minRow = Infinity;
+        let maxRow = -Infinity;
+        let minCol = Infinity;
+        let maxCol = -Infinity;
+        let sheetName = "";
+        for (const range of ranges) {
+            // Parse each range (e.g., "Sheet1!$A$2:$A$20" or "Sheet1!$C$1")
+            const selections = generateSelectionsFromFormula(`=${range}`);
+            if (selections.length > 0) {
+                const sel = selections[0];
+                // Extract sheet name from the first range
+                if (!sheetName && range.includes("!")) {
+                    sheetName = range.split("!")[0];
+                }
+                // Update bounding box
+                minRow = Math.min(minRow, sel.range.startRowIndex);
+                maxRow = Math.max(maxRow, sel.range.endRowIndex);
+                minCol = Math.min(minCol, sel.range.startColumnIndex);
+                maxCol = Math.max(maxCol, sel.range.endColumnIndex);
+            }
+        }
+        if (minRow === Infinity || minCol === Infinity) {
+            return null;
+        }
+        // Convert back to Excel range format
+        const startCell = columnIndexToLetter(minCol) + minRow;
+        const endCell = columnIndexToLetter(maxCol) + maxRow;
+        const rangeStr = startCell === endCell ? startCell : `${startCell}:${endCell}`;
+        return sheetName ? `${sheetName}!${rangeStr}` : rangeStr;
+    }
+    catch (err) {
+        console.log("Error calculating bounding range:", err);
+        return null;
+    }
+}
+// Helper function to convert column index to letter (1 -> A, 2 -> B, etc.)
+function columnIndexToLetter(index) {
+    let result = "";
+    let num = index;
+    while (num > 0) {
+        num--;
+        result = String.fromCharCode(65 + (num % 26)) + result;
+        num = Math.floor(num / 26);
+    }
+    return result;
+}
+/**
+ * Extract hidden dimension strategy from plotVisOnly attribute
+ * In Excel: plotVisOnly="1" means skip hidden rows/columns, "0" means show all
+ */
+export function extractHiddenDimensionStrategy(chart) {
+    const plotVisOnly = getWithFallback(chart, [
+        "c:plotVisOnly.a$.val",
+        "c:plotVisOnly.a$.t$",
+        "plotVisOnly.a$.val",
+        "plotVisOnly.a$.t$",
+    ]);
+    if (plotVisOnly === undefined) {
+        return undefined;
+    }
+    // "1" or "true" = skip hidden cells, "0" or "false" = show all
+    const skipHidden = plotVisOnly === "1" || plotVisOnly === "true" || plotVisOnly === true;
+    return skipHidden ? "SKIP_HIDDEN_ROWS_AND_COLUMNS" : "SHOW_ALL";
+}
+/**
+ * Read the chart title's text formatting. Excel chart titles can be
+ * styled two ways:
+ *  - via `<c:title><c:txPr>` (paragraph default, affects future
+ *    content); writers use this when no inline rich text is present.
+ *  - via `<c:title><c:tx><c:rich>` (the title text itself, with
+ *    per-paragraph `<a:pPr><a:defRPr>` carrying the styling).
+ * We probe both, with the rich-text path winning when present (it's
+ * the more explicit signal). Returns `undefined` when neither carries
+ * formatting so the renderer falls back to its theme defaults.
+ */
+function extractChartTitleTextFormat(chart) {
+    const title = get(chart, "c:title") ?? get(chart, "title");
+    if (!title)
+        return undefined;
+    const richTxPr = get(title, "c:tx.c:rich") ?? get(title, "tx.rich");
+    const fromRich = extractTextProperties(richTxPr);
+    if (fromRich)
+        return fromRich;
+    const txPr = get(title, "c:txPr") ?? get(title, "txPr");
+    return extractTextProperties(txPr);
+}
+export function extractChartTitle(chart) {
+    // Try different possible paths for chart title
+    const title = 
+    // Rich text format (your current structure)
+    get(chart, "c:title.c:tx.c:rich.a:p.a:r.a:t") ||
+        // Alternative rich text paths
+        get(chart, "c:title.c:tx.c:rich.a:p.a:r.a:t.t$") ||
+        // String reference format
+        get(chart, "c:title.c:tx.c:strRef.c:strCache.c:pt.c:v") ||
+        get(chart, "c:title.c:tx.c:strRef.c:strCache.c:pt.c:v.t$") ||
+        // Direct value format
+        get(chart, "c:title.c:tx.c:v") ||
+        get(chart, "c:title.c:tx.c:v.t$") ||
+        // Simple text format
+        get(chart, "c:title.c:tx") ||
+        // Fallback: look for any text in title
+        extractTextFromTitle(get(chart, "c:title")) ||
+        "";
+    return typeof title === "string" ? title : "";
+}
+// Helper function to recursively search for text in title structure
+function extractTextFromTitle(titleObj) {
+    if (!titleObj)
+        return "";
+    // If it's already a string, return it
+    if (typeof titleObj === "string")
+        return titleObj;
+    // Look for common text properties
+    if (titleObj["a:t"])
+        return titleObj["a:t"];
+    if (titleObj.t$)
+        return titleObj.t$;
+    if (titleObj.text)
+        return titleObj.text;
+    if (titleObj.value)
+        return titleObj.value;
+    // Recursively search through nested objects
+    for (const key in titleObj) {
+        if (typeof titleObj[key] === "object") {
+            const result = extractTextFromTitle(titleObj[key]);
+            if (result)
+                return result;
+        }
+    }
+    return "";
+}
+export function determineChartType(chart) {
+    const plotArea = getWithFallback(chart, ["c:plotArea", "plotArea"]);
+    // c15 extension marker (Phase 5.5): if the plotArea's c:extLst tags
+    // the chart as histogram / boxplot / waterfall / funnel, that overrides
+    // the bar-chart fallback the body uses for older-Excel compatibility.
+    const c15Type = detectC15ChartType(plotArea);
+    if (c15Type)
+        return c15Type;
+    const barChart = getWithFallback(plotArea, [
+        "c:barChart",
+        "barChart",
+        "c:bar3DChart",
+        "bar3DChart",
+    ]);
+    if (barChart) {
+        const direction = get(barChart, "c:barDir.a$.val") ||
+            get(barChart, "c:barDir.a$.t$") ||
+            get(barChart, "barDir.a$.val") ||
+            get(barChart, "barDir.a$.t$") ||
+            get(barChart, "c:barDir.a$.v") ||
+            get(barChart, "barDir.a$.v");
+        return direction === "bar" ? "bar" : "column";
+    }
+    if (getWithFallback(plotArea, [
+        "c:lineChart",
+        "lineChart",
+        "c:line3DChart",
+        "line3DChart",
+    ]))
+        return "line";
+    // OOXML uses a dedicated <c:doughnutChart> element. Check it before
+    // <c:pieChart>/<c:ofPieChart> so the more-specific shape wins.
+    if (getWithFallback(plotArea, ["c:doughnutChart", "doughnutChart"]))
+        return "doughnut";
+    // pie-of-pie / bar-of-pie — the renderer draws the composite from a
+    // plain "pie" chartType plus sourceChartType "OF_PIE" and the of-pie
+    // split fields (extracted in extractOfPieOptions).
+    if (getWithFallback(plotArea, ["c:ofPieChart", "ofPieChart"]))
+        return "pie";
+    if (getWithFallback(plotArea, [
+        "c:pieChart",
+        "pieChart",
+        "c:pie3DChart",
+        "pie3DChart",
+    ]))
+        return "pie";
+    if (getWithFallback(plotArea, [
+        "c:areaChart",
+        "areaChart",
+        "c:area3DChart",
+        "area3DChart",
+    ]))
+        return "area";
+    if (getWithFallback(plotArea, ["c:radarChart", "radarChart"]))
+        return "radar";
+    if (getWithFallback(plotArea, ["c:stockChart", "stockChart"]))
+        return "stock";
+    // Scatter and bubble — both use c:xVal/c:yVal series shape (not
+    // c:cat/c:val like other charts). Bubble additionally has c:bubbleSize.
+    if (getWithFallback(plotArea, ["c:scatterChart", "scatterChart"]))
+        return "scatter";
+    if (getWithFallback(plotArea, ["c:bubbleChart", "bubbleChart"]))
+        return "bubble";
+    return "column"; // default
+}
+/**
+ * Phase 5.5 — detect the c15 extension marker our exporter writes on
+ * the plotArea. Returns the originating chart type (histogram /
+ * boxplot / waterfall / funnel) or null if no marker is present.
+ *
+ * The marker shape is:
+ *   c:plotArea > c:extLst > c:ext (uri = ...) > c15:<chartName>Chart
+ *
+ * We accept either array or single-object shape for `c:ext` since
+ * fast-xml-parser normalizes lone children to objects.
+ */
+function detectC15ChartType(plotArea) {
+    if (!plotArea)
+        return null;
+    // Empty c15 elements (`<c15:histogramChart/>`) parse to "" — truthy
+    // checks skip them, so we test for key presence instead.
+    const hasKey = (obj, key) => obj != null && Object.prototype.hasOwnProperty.call(obj, key);
+    // Phase 5.5b: c15 chart wrapped in mc:AlternateContent > mc:Choice.
+    // This is the Excel-native shape — modern Excel renders the chart
+    // from here, older Excel uses mc:Fallback (a c:barChart).
+    const altContent = getWithFallback(plotArea, [
+        "mc:AlternateContent",
+        "AlternateContent",
+    ]);
+    if (altContent) {
+        const choice = getWithFallback(altContent, ["mc:Choice", "Choice"]);
+        if (choice) {
+            const choices = Array.isArray(choice) ? choice : [choice];
+            for (const c of choices) {
+                if (hasKey(c, "c15:histogramChart") || hasKey(c, "histogramChart"))
+                    return "histogram";
+                if (hasKey(c, "c15:boxWhiskerChart") || hasKey(c, "boxWhiskerChart"))
+                    return "boxplot";
+                if (hasKey(c, "c15:waterfallChart") || hasKey(c, "waterfallChart"))
+                    return "waterfall";
+                if (hasKey(c, "c15:funnelChart") || hasKey(c, "funnelChart"))
+                    return "funnel";
+            }
+        }
+    }
+    // Phase 5.5 (legacy): c15 extension marker inside c:extLst > c:ext.
+    // Round-trips through our pipeline; opens as bar chart in Excel.
+    // Kept so files written by older versions of this code still parse.
+    const extLst = getWithFallback(plotArea, ["c:extLst", "extLst"]);
+    if (!extLst)
+        return null;
+    const extNode = getWithFallback(extLst, ["c:ext", "ext"]);
+    if (!extNode)
+        return null;
+    const exts = Array.isArray(extNode) ? extNode : [extNode];
+    for (const ext of exts) {
+        if (!ext)
+            continue;
+        if (hasKey(ext, "c15:histogramChart") || hasKey(ext, "histogramChart"))
+            return "histogram";
+        if (hasKey(ext, "c15:boxWhiskerChart") || hasKey(ext, "boxWhiskerChart"))
+            return "boxplot";
+        if (hasKey(ext, "c15:waterfallChart") || hasKey(ext, "waterfallChart"))
+            return "waterfall";
+        if (hasKey(ext, "c15:funnelChart") || hasKey(ext, "funnelChart"))
+            return "funnel";
+    }
+    return null;
+}
+/**
+ * Phase 5.5 — pull binCount out of the c15:histogramChart extension
+ * marker. Returns undefined if absent.
+ */
+export function extractC15HistogramBinCount(plotArea) {
+    if (!plotArea)
+        return undefined;
+    const readBinCount = (hist) => {
+        if (!hist)
+            return undefined;
+        const raw = get(hist, "c15:binCount.a$.val") ??
+            get(hist, "binCount.a$.val") ??
+            get(hist, "c15:binCount.a$.v") ??
+            get(hist, "binCount.a$.v");
+        if (raw === undefined || raw === null)
+            return undefined;
+        const num = Number(raw);
+        return Number.isFinite(num) ? num : undefined;
+    };
+    // Phase 5.5b: histogram inside mc:AlternateContent > mc:Choice.
+    const altContent = getWithFallback(plotArea, [
+        "mc:AlternateContent",
+        "AlternateContent",
+    ]);
+    if (altContent) {
+        const choice = getWithFallback(altContent, ["mc:Choice", "Choice"]);
+        const choices = Array.isArray(choice)
+            ? choice
+            : choice
+                ? [choice]
+                : [];
+        for (const c of choices) {
+            const hist = c?.["c15:histogramChart"] ?? c?.["histogramChart"] ?? null;
+            const v = readBinCount(hist);
+            if (v !== undefined)
+                return v;
+        }
+    }
+    // Phase 5.5 (legacy): histogram inside c:extLst > c:ext marker.
+    const extLst = getWithFallback(plotArea, ["c:extLst", "extLst"]);
+    if (!extLst)
+        return undefined;
+    const extNode = getWithFallback(extLst, ["c:ext", "ext"]);
+    if (!extNode)
+        return undefined;
+    const exts = Array.isArray(extNode) ? extNode : [extNode];
+    for (const ext of exts) {
+        const hist = ext?.["c15:histogramChart"] ?? ext?.["histogramChart"] ?? null;
+        const v = readBinCount(hist);
+        if (v !== undefined)
+            return v;
+    }
+    return undefined;
+}
+// Chart type containers to search for series. Combo charts can mix
+// multiple containers (e.g. column + line on one chart), so we iterate
+// through all of them. XY charts (scatter/bubble) have a different
+// per-series shape (xVal/yVal/bubbleSize) and require their own series
+// extractor — they're listed here so combo charts that mix XY with
+// non-XY series (rare but valid in OOXML) still pick up both.
+const CHART_TYPE_CONTAINERS = [
+    {
+        paths: ["c:barChart", "barChart", "c:bar3DChart", "bar3DChart"],
+        chartType: "column",
+        isBar: true,
+    },
+    {
+        paths: ["c:lineChart", "lineChart", "c:line3DChart", "line3DChart"],
+        chartType: "line",
+    },
+    {
+        paths: ["c:areaChart", "areaChart", "c:area3DChart", "area3DChart"],
+        chartType: "area",
+    },
+    {
+        paths: ["c:scatterChart", "scatterChart"],
+        chartType: "scatter",
+        isXY: true,
+    },
+    {
+        paths: ["c:bubbleChart", "bubbleChart"],
+        chartType: "bubble",
+        isXY: true,
+    },
+];
+/**
+ * Resolve a chart-formula range string (e.g.
+ * `'Data for the Chart'!$A$7:$A$26`) into the sources array our chart
+ * model expects (one entry per parsed selection, with the data sheet's
+ * sheetId — not the chart's host sheet).
+ */
+function resolveSourcesFromRef(ref, hostSheetId, resolveSheetId) {
+    const selections = generateSelectionsFromFormula(`=${ref}`);
+    return selections.map((sel) => ({
+        ...sel.range,
+        sheetId: pickSheetId(sel.sheetName, hostSheetId, resolveSheetId),
+    }));
+}
+/**
+ * Extract inline values from a `<c:strLit>` or `<c:numLit>` element —
+ * these appear when chart data is embedded directly in the chart XML
+ * rather than referencing the sheet (Event Budget.xlsx uses this for
+ * its `["Estimated", "Actual"]` category labels).
+ *
+ * Returns the values ordered by their `idx` attribute (Excel allows
+ * sparse indices). Returns `undefined` when no inline data is present.
+ */
+function extractInlineValues(node) {
+    if (!node)
+        return undefined;
+    const strLit = get(node, "c:strLit") ?? get(node, "strLit");
+    const numLit = get(node, "c:numLit") ?? get(node, "numLit");
+    const lit = strLit ?? numLit;
+    if (!lit)
+        return undefined;
+    const pts = get(lit, "c:pt") ?? get(lit, "pt");
+    if (!pts)
+        return [];
+    const ptArray = Array.isArray(pts) ? pts : [pts];
+    // Order by the `idx` attribute. Most files emit them in order but
+    // spec permits any order; we honour that to avoid mis-aligning the
+    // first column when authors hand-craft chart XML.
+    const indexed = [];
+    for (const pt of ptArray) {
+        const idxAttr = get(pt, "a$.idx");
+        const idx = idxAttr !== undefined ? Number(idxAttr) : indexed.length;
+        const rawV = get(pt, "c:v") ?? get(pt, "v");
+        let v;
+        if (typeof rawV === "number" || typeof rawV === "boolean") {
+            v = rawV;
+        }
+        else if (numLit && typeof rawV === "string" && rawV.trim() !== "") {
+            const n = Number(rawV);
+            v = Number.isFinite(n) ? n : rawV;
+        }
+        else {
+            v = typeof rawV === "string" ? rawV : String(rawV ?? "");
+        }
+        indexed.push({ idx: Number.isFinite(idx) ? idx : indexed.length, v });
+    }
+    indexed.sort((a, b) => a.idx - b.idx);
+    return indexed.map((entry) => entry.v);
+}
+export function extractChartSeries(plotArea, chartType, sheetId, resolveSheetId) {
+    const series = [];
+    let seriesIndex = 0;
+    // Iterate through all chart type containers to support combo charts
+    for (const container of CHART_TYPE_CONTAINERS) {
+        const chartElement = getWithFallback(plotArea, container.paths);
+        if (!chartElement)
+            continue;
+        // Handle case where chart element is an array (e.g., multiple c:lineChart elements)
+        const chartElements = Array.isArray(chartElement)
+            ? chartElement
+            : [chartElement];
+        for (const singleChartElement of chartElements) {
+            // Determine the actual chart type for this container
+            let seriesChartType = container.chartType;
+            if (container.isBar) {
+                // Check barDir to distinguish bar vs column
+                const direction = get(singleChartElement, "c:barDir.a$.val") ||
+                    get(singleChartElement, "c:barDir.a$.t$") ||
+                    get(singleChartElement, "barDir.a$.val") ||
+                    get(singleChartElement, "barDir.a$.t$");
+                seriesChartType = direction === "bar" ? "bar" : "column";
+            }
+            // Get series elements from this container
+            const seriesElements = getWithFallback(singleChartElement, [
+                "c:ser",
+                "ser",
+            ]);
+            if (!seriesElements)
+                continue;
+            const seriesArray = Array.isArray(seriesElements)
+                ? seriesElements
+                : [seriesElements];
+            for (let i = 0; i < seriesArray.length; i++) {
+                const ser = seriesArray[i];
+                // Scatter/bubble — "series" carries Y values (yVal). Non-XY —
+                // it carries c:val.
+                const valRef = container.isXY
+                    ? getWithFallback(ser, Y_VAL_REF_PATHS)
+                    : getWithFallback(ser, VAL_REF_PATHS);
+                const seriesTitle = extractSeriesTitleFromSeries(ser);
+                const colorInfo = extractSeriesColorInfo(ser);
+                // Resolve the series' value source — preferring the cell-range
+                // reference and falling back to inline `<c:numLit>`/`<c:strLit>`
+                // when there's no range (rare for series values, common for
+                // tiny embedded charts).
+                let sources = [];
+                let inlineValues;
+                if (valRef) {
+                    sources = resolveSourcesFromRef(valRef, sheetId, resolveSheetId);
+                }
+                if (!sources.length) {
+                    const valNode = container.isXY
+                        ? get(ser, "c:yVal") ?? get(ser, "yVal")
+                        : get(ser, "c:val") ?? get(ser, "val");
+                    inlineValues = extractInlineValues(valNode);
+                }
+                if (!sources.length && (!inlineValues || !inlineValues.length)) {
+                    seriesIndex++;
+                    continue;
+                }
+                const trendlines = extractTrendlines(ser);
+                const errorBars = extractErrorBars(ser, sheetId, resolveSheetId);
+                const marker = extractSeriesMarker(ser);
+                const dataPointColors = extractSeriesDataPointColors(ser);
+                const nameRef = getWithFallback(ser, TX_REF_PATHS);
+                // Per-series category reference — charts whose series plot against
+                // different category ranges can't be represented by the single
+                // chart-level domain alone; the exporter prefers this when present.
+                const serCatRef = container.isXY
+                    ? undefined
+                    : getWithFallback(ser, CAT_REF_PATHS);
+                const categorySources = serCatRef
+                    ? resolveSourcesFromRef(serCatRef, sheetId, resolveSheetId)
+                    : [];
+                series.push({
+                    dataLabel: seriesTitle || `Series ${seriesIndex + 1}`,
+                    ...(nameRef ? { dataLabelRef: nameRef } : {}),
+                    ...(categorySources.length ? { categorySources } : {}),
+                    color: colorInfo.color,
+                    ...(colorInfo.noFill ? { noFill: true } : {}),
+                    negativeColor: colorInfo.negativeColor,
+                    invertIfNegative: colorInfo.invertIfNegative,
+                    ...(colorInfo.gradient ? { gradient: colorInfo.gradient } : {}),
+                    // `seriesChartType` is only meaningful for combo charts where
+                    // individual series can override the chart's overall type
+                    // (bar+line, column+line, etc.). XY charts (scatter/bubble)
+                    // aren't part of combo mixing — leave it unset there so the
+                    // renderer falls back to the chart-level chartType.
+                    ...(container.isXY ? {} : { seriesChartType: seriesChartType }),
+                    sources,
+                    ...(inlineValues && inlineValues.length ? { inlineValues } : {}),
+                    ...(trendlines && trendlines.length ? { trendlines } : {}),
+                    ...(errorBars ? { errorBars } : {}),
+                    ...(marker ? { marker } : {}),
+                    ...(dataPointColors && dataPointColors.length
+                        ? { dataPointColors }
+                        : {}),
+                });
+                seriesIndex++;
+            }
+        }
+    }
+    // Fallback: pie/doughnut/radar/stock/ofPie/etc. aren't in
+    // CHART_TYPE_CONTAINERS; they're single-container, type-specific,
+    // and don't combo with other types. Pick up via the type-specific
+    // path-set helper.
+    if (series.length === 0) {
+        const seriesElements = getSeriesElements(plotArea, chartType);
+        if (seriesElements) {
+            const seriesArray = Array.isArray(seriesElements)
+                ? seriesElements
+                : [seriesElements];
+            seriesArray.forEach((ser, index) => {
+                const valRef = isXYChart(chartType)
+                    ? getWithFallback(ser, Y_VAL_REF_PATHS)
+                    : getWithFallback(ser, VAL_REF_PATHS);
+                const seriesTitle = extractSeriesTitleFromSeries(ser);
+                const colorInfo = extractSeriesColorInfo(ser);
+                let sources = [];
+                let inlineValues;
+                if (valRef) {
+                    sources = resolveSourcesFromRef(valRef, sheetId, resolveSheetId);
+                }
+                if (!sources.length) {
+                    const valNode = isXYChart(chartType)
+                        ? get(ser, "c:yVal") ?? get(ser, "yVal")
+                        : get(ser, "c:val") ?? get(ser, "val");
+                    inlineValues = extractInlineValues(valNode);
+                }
+                if (!sources.length && (!inlineValues || !inlineValues.length)) {
+                    return;
+                }
+                const marker = extractSeriesMarker(ser);
+                const dataPointColors = extractSeriesDataPointColors(ser);
+                const nameRef = getWithFallback(ser, TX_REF_PATHS);
+                const serCatRef = isXYChart(chartType)
+                    ? undefined
+                    : getWithFallback(ser, CAT_REF_PATHS);
+                const categorySources = serCatRef
+                    ? resolveSourcesFromRef(serCatRef, sheetId, resolveSheetId)
+                    : [];
+                series.push({
+                    dataLabel: seriesTitle || `Series ${index + 1}`,
+                    ...(nameRef ? { dataLabelRef: nameRef } : {}),
+                    ...(categorySources.length ? { categorySources } : {}),
+                    color: colorInfo.color,
+                    ...(colorInfo.noFill ? { noFill: true } : {}),
+                    negativeColor: colorInfo.negativeColor,
+                    invertIfNegative: colorInfo.invertIfNegative,
+                    ...(colorInfo.gradient ? { gradient: colorInfo.gradient } : {}),
+                    sources,
+                    ...(inlineValues && inlineValues.length ? { inlineValues } : {}),
+                    ...(marker ? { marker } : {}),
+                    ...(dataPointColors && dataPointColors.length
+                        ? { dataPointColors }
+                        : {}),
+                });
+            });
+        }
+    }
+    return series;
+}
+/**
+ * Extract per-data-point color overrides — `<c:dPt>` array inside
+ * `<c:ser>`. Each entry pins a specific category index to its own
+ * fill color (Gantt charts use this to colour individual tasks; pie
+ * charts use it for per-slice colors). Returns `undefined` when there
+ * are no overrides.
+ */
+function extractSeriesDataPointColors(ser) {
+    const raw = get(ser, "c:dPt") ?? get(ser, "dPt");
+    if (!raw)
+        return undefined;
+    const list = Array.isArray(raw) ? raw : [raw];
+    const result = [];
+    for (const dPt of list) {
+        const idxRaw = get(dPt, "c:idx.a$.val") ?? get(dPt, "idx.a$.val");
+        const idx = idxRaw !== undefined ? Number(idxRaw) : NaN;
+        if (!Number.isFinite(idx))
+            continue;
+        const solidFill = get(dPt, "c:spPr.a:solidFill") ?? get(dPt, "spPr.a:solidFill");
+        const color = resolveDrawingColor(solidFill);
+        if (!color)
+            continue;
+        result.push({ idx, color });
+    }
+    return result.length ? result : undefined;
+}
+const MARKER_SYMBOL_SET = new Set([
+    "none",
+    "circle",
+    "square",
+    "diamond",
+    "triangle",
+    "x",
+    "plus",
+    "star",
+    "dash",
+    "dot",
+    "auto",
+    "picture",
+]);
+function extractSeriesMarker(ser) {
+    const raw = get(ser, "c:marker") ?? get(ser, "marker");
+    if (!raw)
+        return undefined;
+    const symbolRaw = get(raw, "c:symbol.a$.val") ??
+        get(raw, "symbol.a$.val") ??
+        get(raw, "c:symbol.a$.t$") ??
+        get(raw, "symbol.a$.t$");
+    const symbol = typeof symbolRaw === "string" &&
+        MARKER_SYMBOL_SET.has(symbolRaw)
+        ? symbolRaw
+        : undefined;
+    const sizeAttr = get(raw, "c:size.a$.val") ??
+        get(raw, "size.a$.val") ??
+        get(raw, "c:size.a$.t$") ??
+        get(raw, "size.a$.t$");
+    const size = sizeAttr !== undefined && sizeAttr !== null && sizeAttr !== ""
+        ? Number(sizeAttr)
+        : undefined;
+    // Marker fill — used when explicit (not derived from series color).
+    const fillRgb = get(raw, "c:spPr.a:solidFill.a:srgbClr.a$.val") ??
+        get(raw, "spPr.solidFill.srgbClr.a$.val");
+    const color = fillRgb ? `#${fillRgb}` : undefined;
+    const result = {};
+    if (symbol)
+        result.symbol = symbol;
+    if (typeof size === "number" && Number.isFinite(size))
+        result.size = size;
+    if (color)
+        result.color = color;
+    return Object.keys(result).length ? result : undefined;
+}
+// ─── Text property extraction (color, font) ──────────────────────────
+// Used by `readAxis`, `extractLegendOptions`, `extractDataLabelsOptions`,
+// `extractChartTitle` to pull `<c:txPr>` / `<a:rPr>` styling so axis
+// labels, data labels, legend entries and chart titles render with
+// their authored colors instead of falling back to the renderer's
+// theme default (the BEP.xlsx import showed all labels as
+// near-black).
+const OFFICE_THEME_FALLBACK = {
+    // Standard Office theme color tokens. We don't try to resolve from
+    // the workbook's actual `xl/theme/themeN.xml` here — the chart is
+    // typically authored against the same theme palette and these
+    // defaults match the in-app theme defaults closely enough that the
+    // visual difference is below noise level.
+    tx1: "#000000",
+    tx2: "#44546A",
+    bg1: "#FFFFFF",
+    bg2: "#E7E6E6",
+    dk1: "#000000",
+    dk2: "#44546A",
+    lt1: "#FFFFFF",
+    lt2: "#E7E6E6",
+    accent1: "#4472C4",
+    accent2: "#ED7D31",
+    accent3: "#A5A5A5",
+    accent4: "#FFC000",
+    accent5: "#5B9BD5",
+    accent6: "#70AD47",
+    hlink: "#0563C1",
+    folHlink: "#954F72",
+};
+/**
+ * Apply OOXML lumMod / lumOff / shade / tint modifiers to a base RGB
+ * color. All are stored as 1000ths of a percent (75000 = 75%).
+ *
+ * - `lumMod` scales each channel (`c * mod`)
+ * - `lumOff` adds toward white (`+ 255 * off`)
+ * - `shade` darkens — interpolates toward black (`c * shade`)
+ * - `tint` lightens — interpolates toward white (`c + (255 - c) * tint`)
+ *
+ * Order: shade/tint apply first (they're independent transforms), then
+ * lumMod/lumOff. Matches Excel's behaviour closely for common patterns:
+ *   - `tx1 + lumMod=75% + lumOff=25%` → `#404040` dark gray (BEP)
+ *   - `accent1 + shade=76%` → darker accent1 (Gantt)
+ */
+const applyLumModOff = (hex, lumMod, lumOff, shade, tint) => {
+    const m = /^#?([0-9a-fA-F]{6})$/.exec(hex);
+    if (!m)
+        return hex;
+    const v = parseInt(m[1], 16);
+    let r = (v >> 16) & 0xff;
+    let g = (v >> 8) & 0xff;
+    let b = v & 0xff;
+    // shade darkens (multiply by factor < 1); tint lightens (interp
+    // toward white). Apply before lumMod/lumOff since those mix in a
+    // different luminance space and Excel evaluates shade/tint first.
+    if (typeof shade === "number" && shade > 0 && shade < 1) {
+        r = r * shade;
+        g = g * shade;
+        b = b * shade;
+    }
+    if (typeof tint === "number" && tint > 0 && tint < 1) {
+        r = r + (255 - r) * tint;
+        g = g + (255 - g) * tint;
+        b = b + (255 - b) * tint;
+    }
+    const mod = typeof lumMod === "number" ? lumMod : 1;
+    const off = typeof lumOff === "number" ? lumOff : 0;
+    const apply = (c) => Math.max(0, Math.min(255, Math.round(c * mod + 255 * off)));
+    const toHex = (c) => c.toString(16).padStart(2, "0").toUpperCase();
+    return `#${toHex(apply(r))}${toHex(apply(g))}${toHex(apply(b))}`;
+};
+/**
+ * Resolve a DrawingML `<a:solidFill>` (or any element that wraps an
+ * `<a:srgbClr>` / `<a:schemeClr>`) to a hex color string. Handles
+ * `lumMod`/`lumOff` modifiers used to derive grays from theme tokens.
+ */
+function resolveDrawingColor(node) {
+    if (!node)
+        return undefined;
+    // Direct RGB.
+    const srgb = get(node, "a:srgbClr.a$.val") ?? get(node, "srgbClr.a$.val");
+    if (srgb) {
+        const lumMod = readPctNumber(get(node, "a:srgbClr.a:lumMod.a$.val") ??
+            get(node, "srgbClr.lumMod.a$.val"));
+        const lumOff = readPctNumber(get(node, "a:srgbClr.a:lumOff.a$.val") ??
+            get(node, "srgbClr.lumOff.a$.val"));
+        const shade = readPctNumber(get(node, "a:srgbClr.a:shade.a$.val") ??
+            get(node, "srgbClr.shade.a$.val"));
+        const tint = readPctNumber(get(node, "a:srgbClr.a:tint.a$.val") ??
+            get(node, "srgbClr.tint.a$.val"));
+        return applyLumModOff(`#${srgb}`, lumMod, lumOff, shade, tint);
+    }
+    // Theme reference.
+    const schemeName = get(node, "a:schemeClr.a$.val") ?? get(node, "schemeClr.a$.val");
+    if (typeof schemeName === "string") {
+        const base = OFFICE_THEME_FALLBACK[schemeName] ?? "#000000";
+        const lumMod = readPctNumber(get(node, "a:schemeClr.a:lumMod.a$.val") ??
+            get(node, "schemeClr.lumMod.a$.val"));
+        const lumOff = readPctNumber(get(node, "a:schemeClr.a:lumOff.a$.val") ??
+            get(node, "schemeClr.lumOff.a$.val"));
+        const shade = readPctNumber(get(node, "a:schemeClr.a:shade.a$.val") ??
+            get(node, "schemeClr.shade.a$.val"));
+        const tint = readPctNumber(get(node, "a:schemeClr.a:tint.a$.val") ??
+            get(node, "schemeClr.tint.a$.val"));
+        return applyLumModOff(base, lumMod, lumOff, shade, tint);
+    }
+    return undefined;
+}
+/** Parse an OOXML percentage stored as 1000ths-of-a-percent → 0..1. */
+function readPctNumber(val) {
+    if (val === undefined || val === null || val === "")
+        return undefined;
+    const n = Number(val);
+    return Number.isFinite(n) ? n / 100000 : undefined;
+}
+/**
+ * Extract a `ChartTextFormat` from an OOXML text-properties node. The
+ * input is typically `<c:txPr>` or `<c:title><c:tx><c:rich>` — both
+ * use the same `<a:p><a:pPr><a:defRPr>…</a:defRPr></a:pPr></a:p>`
+ * shape to express paragraph-default character properties.
+ *
+ * Returns `undefined` when the node carries no formatting (so the
+ * caller doesn't emit an empty `textFormat` field).
+ */
+function extractTextProperties(txPr) {
+    if (!txPr)
+        return undefined;
+    // The font/color lives on `<a:p><a:pPr><a:defRPr>`. Some writers put
+    // it directly on `<a:r><a:rPr>` for rich titles — accept both.
+    const defRPr = get(txPr, "a:p.a:pPr.a:defRPr") ??
+        get(txPr, "p.pPr.defRPr") ??
+        get(txPr, "a:p.a:r.a:rPr") ??
+        get(txPr, "p.r.rPr");
+    if (!defRPr)
+        return undefined;
+    const result = {};
+    // Font size — `sz` is in 100ths of a point (`sz="900"` → 9pt).
+    const szAttr = get(defRPr, "a$.sz") ?? get(defRPr, "a$.t$");
+    if (szAttr !== undefined && szAttr !== null && szAttr !== "") {
+        const sz = Number(szAttr);
+        if (Number.isFinite(sz) && sz > 0)
+            result.fontSize = sz / 100;
+    }
+    // Bold / italic / underline / strikethrough.
+    const bAttr = get(defRPr, "a$.b");
+    if (bAttr === "1" || bAttr === 1 || bAttr === true)
+        result.bold = true;
+    const iAttr = get(defRPr, "a$.i");
+    if (iAttr === "1" || iAttr === 1 || iAttr === true)
+        result.italic = true;
+    const uAttr = get(defRPr, "a$.u");
+    if (typeof uAttr === "string" && uAttr !== "none")
+        result.underline = true;
+    const strikeAttr = get(defRPr, "a$.strike");
+    if (typeof strikeAttr === "string" && strikeAttr !== "noStrike") {
+        result.strikethrough = true;
+    }
+    // Font family — `<a:latin typeface="…">`.
+    const latin = get(defRPr, "a:latin.a$.typeface") ?? get(defRPr, "latin.a$.typeface");
+    if (typeof latin === "string" && latin)
+        result.fontFamily = latin;
+    // Color — `<a:solidFill>` containing `<a:srgbClr>` or `<a:schemeClr>`.
+    const solidFill = get(defRPr, "a:solidFill") ?? get(defRPr, "solidFill");
+    const color = resolveDrawingColor(solidFill);
+    if (color)
+        result.color = color;
+    return Object.keys(result).length ? result : undefined;
+}
+/**
+ * Read bar/column `<c:grouping>`, `<c:overlap>`, `<c:gapWidth>` —
+ * controls how multi-series bars are arranged (clustered / stacked /
+ * percent-stacked). Looks inside `<c:barChart>` / `<c:bar3DChart>`
+ * containers; returns `undefined` if no settings are present so the
+ * renderer keeps its defaults.
+ */
+function extractBarLayoutOptions(plotArea) {
+    const bar = get(plotArea, "c:barChart") ??
+        get(plotArea, "barChart") ??
+        get(plotArea, "c:bar3DChart") ??
+        get(plotArea, "bar3DChart");
+    if (!bar)
+        return undefined;
+    // `<c:grouping val="clustered|stacked|percentStacked|standard"/>`.
+    // `standard` is "side-by-side, no stacking" — same as `clustered`
+    // semantically; map both to UNSTACKED.
+    const groupingVal = get(bar, "c:grouping.a$.val") ??
+        get(bar, "grouping.a$.val") ??
+        get(bar, "c:grouping.a$.t$") ??
+        get(bar, "grouping.a$.t$");
+    let stackedType;
+    switch (groupingVal) {
+        case "stacked":
+            stackedType = "STACKED";
+            break;
+        case "percentStacked":
+            stackedType = "PERCENT_STACKED";
+            break;
+        case "clustered":
+        case "standard":
+            stackedType = "UNSTACKED";
+            break;
+    }
+    const overlapVal = readNumber(get(bar, "c:overlap.a$.val") ?? get(bar, "overlap.a$.val"));
+    const gapWidthVal = readNumber(get(bar, "c:gapWidth.a$.val") ?? get(bar, "gapWidth.a$.val"));
+    const result = {};
+    if (stackedType)
+        result.stackedType = stackedType;
+    if (typeof overlapVal === "number")
+        result.overlap = overlapVal;
+    if (typeof gapWidthVal === "number")
+        result.gapWidth = gapWidthVal;
+    return Object.keys(result).length ? result : undefined;
+}
+/**
+ * Extract chart-level `<c:scatterStyle val=…>`. Excel default is
+ * "lineMarker" (straight lines + markers). Returns undefined for
+ * non-scatter charts.
+ */
+function extractScatterStyle(plotArea) {
+    const val = get(plotArea, "c:scatterChart.c:scatterStyle.a$.val") ??
+        get(plotArea, "scatterChart.scatterStyle.a$.val") ??
+        get(plotArea, "c:scatterChart.c:scatterStyle.a$.t$") ??
+        get(plotArea, "scatterChart.scatterStyle.a$.t$");
+    return typeof val === "string" && val ? val : undefined;
+}
+function extractSeriesTitleFromSeries(ser) {
+    // Prefer cached textual value if present
+    const cacheEntries = get(ser, "c:tx.c:strRef.c:strCache.c:pt");
+    if (cacheEntries) {
+        const pts = Array.isArray(cacheEntries) ? cacheEntries : [cacheEntries];
+        for (const pt of pts) {
+            const value = coerceTitleText(get(pt, "c:v.t$") ||
+                get(pt, "c:v") ||
+                extractRichText(get(pt, "c:rich")));
+            if (value) {
+                return value;
+            }
+        }
+    }
+    // Fall back to literal
+    const literal = coerceTitleText(get(ser, "c:tx.c:v.t$") ||
+        get(ser, "c:tx.c:v") ||
+        extractRichText(get(ser, "c:tx.c:rich")));
+    if (literal) {
+        return literal;
+    }
+    return undefined;
+}
+/**
+ * fast-xml-parser converts numeric `<c:v>` values (e.g. a series header
+ * like 2024) into numbers; normalize primitives to strings and drop
+ * anything else so titles are always strings downstream.
+ */
+function coerceTitleText(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    return undefined;
+}
+function extractRichText(node) {
+    if (!node) {
+        return undefined;
+    }
+    const paragraphs = getWithFallback(node, ["a:p", "p"]);
+    const paragraphArray = Array.isArray(paragraphs)
+        ? paragraphs
+        : paragraphs
+            ? [paragraphs]
+            : [];
+    const fragments = [];
+    for (const paragraph of paragraphArray) {
+        const runs = getWithFallback(paragraph, ["a:r", "r"]);
+        const runArray = Array.isArray(runs) ? runs : runs ? [runs] : [paragraph];
+        for (const run of runArray) {
+            const text = getWithFallback(run, ["a:t.t$", "a:t"]) ||
+                getWithFallback(run, ["t$", "t"]);
+            if (typeof text === "string") {
+                fragments.push(text);
+            }
+        }
+    }
+    if (fragments.length > 0) {
+        return fragments.join("");
+    }
+    return undefined;
+}
+function normalizeHexColor(value) {
+    if (!value)
+        return undefined;
+    const trimmed = value.toString().trim().replace(/^#/, "");
+    if (!trimmed)
+        return undefined;
+    const sanitized = trimmed.replace(/[^0-9a-fA-F]/g, "").toUpperCase();
+    if (sanitized.length === 6) {
+        return `#${sanitized}`;
+    }
+    if (sanitized.length === 8) {
+        return `#${sanitized.slice(-6)}`;
+    }
+    return undefined;
+}
+function extractSeriesColorInfo(ser) {
+    const result = {};
+    // <a:noFill/> on the series shape properties — transparent series.
+    // OOXML can express this as the singleton element with no children;
+    // the absence of a:solidFill / a:gradFill is also a signal but
+    // brittler. fast-xml-parser emits `noFill: ""` or `noFill: {}` for
+    // empty elements — both falsy by-value but truthy by-presence.
+    const noFillFill = get(ser, "c:spPr.a:noFill") ?? get(ser, "spPr.a:noFill");
+    if (noFillFill !== undefined) {
+        result.noFill = true;
+    }
+    // Try the full <a:solidFill> shape first — handles both srgbClr
+    // and schemeClr (with lumMod/lumOff/shade/tint/alpha modifiers).
+    const solidFillNode = get(ser, "c:spPr.a:solidFill") ?? get(ser, "spPr.a:solidFill");
+    const resolvedFill = resolveDrawingColor(solidFillNode);
+    // Extract main color - check both fill color (for bar/column) and line color (for line/area charts)
+    const fillColorValue = getWithFallback(ser, [
+        "c:spPr.a:solidFill.a:srgbClr.a$.val",
+        "c:spPr.a:solidFill.a:srgbClr.a$.t$",
+        "c:spPr.a:solidFill.a:srgbClr.a$.rgb",
+        "c:spPr.solidFill.srgbClr.a$.val",
+        "spPr.a:solidFill.a:srgbClr.a$.val",
+        "spPr.solidFill.srgbClr.a$.val",
+    ]);
+    // Line color for line/scatter/area charts
+    const lineColorValue = getWithFallback(ser, [
+        "c:spPr.a:ln.a:solidFill.a:srgbClr.a$.val",
+        "c:spPr.a:ln.a:solidFill.a:srgbClr.a$.t$",
+        "c:spPr.a:ln.a:solidFill.a:srgbClr.a$.rgb",
+        "c:spPr.a:ln.solidFill.srgbClr.a$.val",
+        "spPr.a:ln.a:solidFill.a:srgbClr.a$.val",
+        "spPr.ln.solidFill.srgbClr.a$.val",
+    ]);
+    // Use fill color if available, otherwise use line color.
+    // resolvedFill handles schemeClr; the legacy normalize call handles
+    // the explicit srgbClr path (kept as a fallback). When noFill is set
+    // we leave `color` undefined — the renderer treats the series as
+    // transparent.
+    if (!result.noFill) {
+        result.color =
+            resolvedFill ??
+                normalizeHexColor(fillColorValue) ??
+                normalizeHexColor(lineColorValue);
+    }
+    // Gradient fill — DrawingML `<a:gradFill>` inside `<c:spPr>`. Stops
+    // come in EMU per-mille (0..100000); positions get normalized back
+    // to 0..1 for our shape. Linear angle is in 60000ths of a degree;
+    // path gradients carry insets via `<a:path><a:fillToRect/>`.
+    const gradFill = getWithFallback(ser, [
+        "c:spPr.a:gradFill",
+        "spPr.a:gradFill",
+        "c:spPr.gradFill",
+    ]);
+    if (gradFill) {
+        const rawStops = getWithFallback(gradFill, [
+            "a:gsLst.a:gs",
+            "gsLst.gs",
+        ]);
+        const stopList = rawStops
+            ? Array.isArray(rawStops)
+                ? rawStops
+                : [rawStops]
+            : [];
+        const stops = [];
+        for (const stop of stopList) {
+            const posRaw = stop?.a$?.pos;
+            const position = posRaw != null
+                ? Math.max(0, Math.min(1, parseFloat(posRaw) / 100000))
+                : NaN;
+            if (!Number.isFinite(position))
+                continue;
+            const hex = getWithFallback(stop, [
+                "a:srgbClr.a$.val",
+                "srgbClr.a$.val",
+            ]);
+            const color = normalizeHexColor(hex);
+            if (!color)
+                continue;
+            stops.push({ position, color });
+        }
+        if (stops.length > 0) {
+            stops.sort((a, b) => a.position - b.position);
+            const lin = getWithFallback(gradFill, ["a:lin.a$", "lin.a$"]);
+            const path = getWithFallback(gradFill, ["a:path", "path"]);
+            if (path) {
+                const insets = getWithFallback(path, [
+                    "a:fillToRect.a$",
+                    "fillToRect.a$",
+                ]);
+                const emuToFraction = (v) => {
+                    if (v == null)
+                        return undefined;
+                    const n = parseFloat(v);
+                    return Number.isFinite(n) ? n / 100000 : undefined;
+                };
+                result.gradient = {
+                    type: "path",
+                    left: emuToFraction(insets?.l),
+                    right: emuToFraction(insets?.r),
+                    top: emuToFraction(insets?.t),
+                    bottom: emuToFraction(insets?.b),
+                    stops,
+                };
+            }
+            else {
+                const ang = lin?.ang != null ? parseFloat(lin.ang) : 0;
+                result.gradient = {
+                    type: "linear",
+                    degree: Number.isFinite(ang) ? ang / 60000 : 0,
+                    stops,
+                };
+            }
+        }
+    }
+    // Extract invertIfNegative flag
+    const invertIfNegativeVal = getWithFallback(ser, [
+        "c:invertIfNegative.a$.val",
+        "c:invertIfNegative.t$",
+        "c:invertIfNegative",
+        "invertIfNegative.a$.val",
+        "invertIfNegative",
+    ]);
+    // Value can be "1", "true", true, or 1
+    if (invertIfNegativeVal !== undefined) {
+        result.invertIfNegative =
+            invertIfNegativeVal === "1" ||
+                invertIfNegativeVal === true ||
+                invertIfNegativeVal === 1 ||
+                invertIfNegativeVal === "true";
+    }
+    // Extract negative fill color from extLst (Excel 2010+ format)
+    // The negative color is stored in c:extLst.c:ext with specific URI
+    const extLst = getWithFallback(ser, [
+        "c:extLst.c:ext",
+        "c:extLst",
+        "extLst.ext",
+        "extLst",
+    ]);
+    if (extLst) {
+        const extArray = Array.isArray(extLst) ? extLst : [extLst];
+        for (const ext of extArray) {
+            // Look for invertSolidFillFmt extension (negative fill format)
+            const negFillColor = getWithFallback(ext, [
+                "c14:invertSolidFillFmt.c14:spPr.a:solidFill.a:srgbClr.a$.val",
+                "c14:invertSolidFillFmt.c14:spPr.a:solidFill.a:srgbClr.a$.rgb",
+                "invertSolidFillFmt.spPr.solidFill.srgbClr.a$.val",
+                // Also check for c15 namespace (Excel 2013+)
+                "c15:invertSolidFillFmt.c15:spPr.a:solidFill.a:srgbClr.a$.val",
+            ]);
+            if (negFillColor) {
+                result.negativeColor = normalizeHexColor(negFillColor);
+                // If we have a negative color, invertIfNegative should be true
+                if (result.negativeColor) {
+                    result.invertIfNegative = true;
+                }
+                break;
+            }
+        }
+    }
+    return result;
+}
+export function extractChartDomains(plotArea, chartType, sheetId, resolveSheetId) {
+    const domains = [];
+    // Search all chart type containers for domains. For XY charts the
+    // "domain" is the X values (c:xVal); for everything else it's the
+    // category axis (c:cat). Per-container loop covers combo charts.
+    for (const container of CHART_TYPE_CONTAINERS) {
+        const chartElement = getWithFallback(plotArea, container.paths);
+        if (!chartElement)
+            continue;
+        const chartElements = Array.isArray(chartElement)
+            ? chartElement
+            : [chartElement];
+        for (const singleChartElement of chartElements) {
+            const seriesElements = getWithFallback(singleChartElement, [
+                "c:ser",
+                "ser",
+            ]);
+            if (!seriesElements)
+                continue;
+            const seriesArray = Array.isArray(seriesElements)
+                ? seriesElements
+                : [seriesElements];
+            for (const ser of seriesArray) {
+                const domainRef = container.isXY
+                    ? getWithFallback(ser, X_VAL_REF_PATHS)
+                    : getWithFallback(ser, CAT_REF_PATHS);
+                if (domainRef) {
+                    const sources = resolveSourcesFromRef(domainRef, sheetId, resolveSheetId);
+                    if (sources.length) {
+                        domains.push({ sources });
+                        // XY charts may carry per-series domains that differ — keep
+                        // the first one we encounter for the dataRange anchor, but
+                        // continue collecting so the renderer has a per-series X
+                        // when it needs one. For non-XY, first-found is enough.
+                        if (!container.isXY)
+                            return domains;
+                    }
+                }
+                else if (!container.isXY) {
+                    // No cell ref — check for an inline `<c:strLit>`/`<c:numLit>`
+                    // category list (e.g. `["Estimated", "Actual"]` embedded
+                    // directly in the chart XML). Same for the series val side,
+                    // but domains is by far the most common case.
+                    const catNode = get(ser, "c:cat") ?? get(ser, "cat");
+                    const inlineValues = extractInlineValues(catNode);
+                    if (inlineValues && inlineValues.length) {
+                        domains.push({ sources: [], inlineValues });
+                        return domains;
+                    }
+                }
+            }
+            if (domains.length && container.isXY)
+                return domains;
+        }
+    }
+    // Fallback for chart types not in CHART_TYPE_CONTAINERS
+    // (pie/doughnut/radar/stock/ofPie/scatter/bubble outside combos).
+    const seriesElements = getSeriesElements(plotArea, chartType);
+    if (seriesElements) {
+        const seriesArray = Array.isArray(seriesElements)
+            ? seriesElements
+            : [seriesElements];
+        for (const ser of seriesArray) {
+            const domainRef = isXYChart(chartType)
+                ? getWithFallback(ser, X_VAL_REF_PATHS)
+                : getWithFallback(ser, CAT_REF_PATHS);
+            if (domainRef) {
+                const sources = resolveSourcesFromRef(domainRef, sheetId, resolveSheetId);
+                if (sources.length) {
+                    domains.push({ sources });
+                    if (!isXYChart(chartType))
+                        break;
+                }
+            }
+            else if (!isXYChart(chartType)) {
+                const catNode = get(ser, "c:cat") ?? get(ser, "cat");
+                const inlineValues = extractInlineValues(catNode);
+                if (inlineValues && inlineValues.length) {
+                    domains.push({ sources: [], inlineValues });
+                    break;
+                }
+            }
+        }
+    }
+    return domains;
+}
+/**
+ * Bubble charts have a third dimension — bubble size — referenced
+ * via `<c:bubbleSize><c:numRef><c:f>` on each series. Returns one
+ * `ChartData` entry per series (matches the shape used by `domains` /
+ * `series`).
+ */
+export function extractChartBubbleSizes(plotArea, sheetId, resolveSheetId) {
+    const sizes = [];
+    const seriesElements = getSeriesElements(plotArea, "bubble");
+    if (!seriesElements)
+        return sizes;
+    const seriesArray = Array.isArray(seriesElements)
+        ? seriesElements
+        : [seriesElements];
+    for (const ser of seriesArray) {
+        const sizeRef = getWithFallback(ser, BUBBLE_SIZE_REF_PATHS);
+        if (!sizeRef)
+            continue;
+        const sources = resolveSourcesFromRef(sizeRef, sheetId, resolveSheetId);
+        if (sources.length)
+            sizes.push({ sources });
+    }
+    return sizes;
+}
+export function extractChartPosition(anchor, sheetId, sheetDimensions) {
+    try {
+        // Handle oneCellAnchor
+        const oneCellFrom = getWithFallback(anchor, ["xdr:from", "from"]) ?? undefined;
+        const hasTwoCellTarget = getWithFallback(anchor, ["xdr:to", "to"]) !== undefined;
+        if (oneCellFrom && !hasTwoCellTarget) {
+            const extNode = getWithFallback(anchor, ["xdr:ext", "ext"]);
+            const extAttributes = (extNode && (extNode.a$ ?? extNode)) || undefined;
+            const col = toInt(getWithFallback(oneCellFrom, ["xdr:col", "col"]));
+            const row = toInt(getWithFallback(oneCellFrom, ["xdr:row", "row"]));
+            const colOff = toInt(getWithFallback(oneCellFrom, ["xdr:colOff", "colOff"]));
+            const rowOff = toInt(getWithFallback(oneCellFrom, ["xdr:rowOff", "rowOff"]));
+            // Convert EMU to pixels (1 EMU = 1/9525 pixels)
+            const width = extAttributes && extAttributes.cx
+                ? Math.round(parseInt(String(extAttributes.cx), 10) / 9525)
+                : 400;
+            const height = extAttributes && extAttributes.cy
+                ? Math.round(parseInt(String(extAttributes.cy), 10) / 9525)
+                : 300;
+            return {
+                sheetId,
+                overlayPosition: {
+                    anchorCell: {
+                        rowIndex: row + 1,
+                        columnIndex: col + 1,
+                    },
+                    offsetXPixels: Math.round(colOff / 9525),
+                    offsetYPixels: Math.round(rowOff / 9525),
+                    widthPixels: width,
+                    heightPixels: height,
+                },
+            };
+        }
+        // Handle twoCellAnchor
+        const fromCell = getWithFallback(anchor, ["xdr:from", "from"]) ?? undefined;
+        const toCell = getWithFallback(anchor, ["xdr:to", "to"]) ?? undefined;
+        if (fromCell && toCell) {
+            const col = toInt(getWithFallback(fromCell, ["xdr:col", "col"]));
+            const row = toInt(getWithFallback(fromCell, ["xdr:row", "row"]));
+            const colOff = toInt(getWithFallback(fromCell, ["xdr:colOff", "colOff"]));
+            const rowOff = toInt(getWithFallback(fromCell, ["xdr:rowOff", "rowOff"]));
+            const toCol = toInt(getWithFallback(toCell, ["xdr:col", "col"]));
+            const toRow = toInt(getWithFallback(toCell, ["xdr:row", "row"]));
+            const toColOff = toInt(getWithFallback(toCell, ["xdr:colOff", "colOff"]));
+            const toRowOff = toInt(getWithFallback(toCell, ["xdr:rowOff", "rowOff"]));
+            // Default cell dimensions in pixels
+            const DEFAULT_COL_WIDTH_PX = sheetDimensions?.defaultColumnWidth ?? 64;
+            const DEFAULT_ROW_HEIGHT_PX = sheetDimensions?.defaultRowHeight ?? 20;
+            // Helper to get column width in pixels
+            const getColWidth = (colIndex) => {
+                return (sheetDimensions?.columnWidths?.get(colIndex + 1) ??
+                    DEFAULT_COL_WIDTH_PX);
+            };
+            // Helper to get row height in pixels
+            const getRowHeight = (rowIndex) => {
+                return (sheetDimensions?.rowHeights?.get(rowIndex + 1) ??
+                    DEFAULT_ROW_HEIGHT_PX);
+            };
+            // Calculate width by summing actual column widths
+            let widthPx = 0;
+            for (let c = col; c < toCol; c++) {
+                widthPx += getColWidth(c);
+            }
+            // Subtract offset into first cell, add offset into last cell
+            // Offsets are in EMUs, convert to pixels
+            widthPx -= Math.round(colOff / 9525);
+            widthPx += Math.round(toColOff / 9525);
+            // Calculate height by summing actual row heights
+            let heightPx = 0;
+            for (let r = row; r < toRow; r++) {
+                heightPx += getRowHeight(r);
+            }
+            // Subtract offset into first cell, add offset into last cell
+            heightPx -= Math.round(rowOff / 9525);
+            heightPx += Math.round(toRowOff / 9525);
+            const width = Math.max(widthPx, 100);
+            const height = Math.max(heightPx, 100);
+            return {
+                sheetId,
+                overlayPosition: {
+                    anchorCell: {
+                        rowIndex: row + 1,
+                        columnIndex: col + 1,
+                    },
+                    offsetXPixels: Math.round(colOff / 9525),
+                    offsetYPixels: Math.round(rowOff / 9525),
+                    widthPixels: width,
+                    heightPixels: height,
+                },
+            };
+        }
+        return null;
+    }
+    catch (err) {
+        console.log("Error extracting chart position:", err);
+        return null;
+    }
+}
+// -------------------------- Phase 5 helpers --------------------------
+// Read OOXML legend (<c:legend>), data labels (<c:dLbls>), and axis
+// formatting (<c:valAx>, <c:catAx>) elements into the engine's ChartSpec
+// shape. All helpers return `undefined` when nothing meaningful is set,
+// so callers can spread the result without polluting the spec.
+const readBoolean = (val) => {
+    if (val === undefined || val === null)
+        return undefined;
+    return val === "1" || val === "true" || val === true;
+};
+const readNumber = (val) => {
+    if (val === undefined || val === null)
+        return undefined;
+    const n = typeof val === "number" ? val : parseFloat(String(val));
+    return Number.isFinite(n) ? n : undefined;
+};
+const mapLegendPosition = (val) => {
+    switch (val) {
+        case "t":
+            return "top";
+        case "b":
+            return "bottom";
+        case "l":
+            return "left";
+        case "r":
+            return "right";
+        case "tr":
+            return "topRight";
+        default:
+            return undefined;
+    }
+};
+function extractLegendOptions(chart) {
+    // OOXML omits <c:legend> when the chart hides the legend, but
+    // includes it (possibly empty) when the legend is shown. Some
+    // writers add a child <c:delete val="1"/> instead — handle that too.
+    const legend = getWithFallback(chart, ["c:legend", "legend"]);
+    if (legend === undefined) {
+        // Excel's default is "show". We only emit a `legend` field when the
+        // source explicitly suppressed it, otherwise renderers fall back.
+        return undefined;
+    }
+    const deleted = readBoolean(get(legend, "c:delete.a$.val") ?? get(legend, "delete.a$.val"));
+    if (deleted) {
+        return { position: "none" };
+    }
+    const posVal = get(legend, "c:legendPos.a$.val") ?? get(legend, "legendPos.a$.val");
+    const position = mapLegendPosition(posVal);
+    const textFormat = extractTextProperties(get(legend, "c:txPr") ?? get(legend, "txPr"));
+    if (!position && !textFormat)
+        return undefined;
+    return {
+        ...(position ? { position } : {}),
+        ...(textFormat ? { textFormat } : {}),
+    };
+}
+const mapDataLabelPosition = (val) => {
+    switch (val) {
+        case "ctr":
+            return "center";
+        case "inEnd":
+            return "insideEnd";
+        case "inBase":
+            return "inside";
+        case "outEnd":
+            return "outsideEnd";
+        case "bestFit":
+            return "bestFit";
+        default:
+            return undefined;
+    }
+};
+function extractDataLabelsOptions(plotArea, chartType) {
+    // Look for <c:dLbls> inside the chartType-specific container. We pick
+    // the first one we find — chart-level labels apply to all series.
+    const containerKeys = {
+        bar: ["c:barChart", "barChart"],
+        column: ["c:barChart", "barChart"],
+        line: ["c:lineChart", "lineChart"],
+        pie: ["c:pieChart", "pieChart", "c:ofPieChart", "ofPieChart"],
+        doughnut: ["c:doughnutChart", "doughnutChart"],
+        area: ["c:areaChart", "areaChart"],
+    };
+    const keys = containerKeys[chartType] ?? [];
+    let container;
+    for (const key of keys) {
+        container = container ?? get(plotArea, key);
+    }
+    const dLbls = get(container, "c:dLbls") ??
+        get(container, "dLbls") ??
+        get(plotArea, "c:dLbls") ??
+        get(plotArea, "dLbls");
+    if (!dLbls)
+        return undefined;
+    const result = {};
+    const pos = get(dLbls, "c:dLblPos.a$.val") ?? get(dLbls, "dLblPos.a$.val");
+    const position = mapDataLabelPosition(pos);
+    if (position)
+        result.position = position;
+    const showVal = readBoolean(get(dLbls, "c:showVal.a$.val") ?? get(dLbls, "showVal.a$.val"));
+    if (showVal) {
+        result.show = true;
+        result.showValue = true;
+    }
+    const showCat = readBoolean(get(dLbls, "c:showCatName.a$.val") ?? get(dLbls, "showCatName.a$.val"));
+    if (showCat) {
+        result.show = true;
+        result.showCategoryName = true;
+    }
+    const showPct = readBoolean(get(dLbls, "c:showPercent.a$.val") ?? get(dLbls, "showPercent.a$.val"));
+    if (showPct) {
+        result.show = true;
+        result.showPercent = true;
+    }
+    const showSer = readBoolean(get(dLbls, "c:showSerName.a$.val") ?? get(dLbls, "showSerName.a$.val"));
+    if (showSer) {
+        result.show = true;
+        result.showSeriesName = true;
+    }
+    // If only `position` was set with no `show*` flags, treat as "show".
+    if (position && result.show === undefined)
+        result.show = true;
+    // <c:txPr> on the dLbls block — affects every label in the chart.
+    const textFormat = extractTextProperties(get(dLbls, "c:txPr") ?? get(dLbls, "txPr"));
+    if (textFormat)
+        result.textFormat = textFormat;
+    // <c:numFmt formatCode="…"/> — Excel uses this to render labels as
+    // currency / percent / etc. (`"$"#,##0`, `0.00%`). Without parsing
+    // this, the renderer falls back to raw numbers (e.g. `1831` instead
+    // of `$1,831`).
+    const numFmt = get(dLbls, "c:numFmt.a$.formatCode") ??
+        get(dLbls, "numFmt.a$.formatCode") ??
+        get(dLbls, "c:numFmt.a$.t$") ??
+        get(dLbls, "numFmt.a$.t$");
+    if (typeof numFmt === "string" && numFmt) {
+        result.numberFormatPattern = numFmt;
+    }
+    return Object.keys(result).length ? result : undefined;
+}
+function readAxis(axis) {
+    if (!axis)
+        return undefined;
+    const result = {};
+    // <c:scaling><c:logBase val="…"/> + <c:orientation val="minMax|maxMin"/>
+    const logBase = readNumber(get(axis, "c:scaling.c:logBase.a$.val") ??
+        get(axis, "scaling.logBase.a$.val"));
+    if (typeof logBase === "number" && logBase > 0)
+        result.logarithmic = true;
+    const orientation = get(axis, "c:scaling.c:orientation.a$.val") ??
+        get(axis, "scaling.orientation.a$.val");
+    if (orientation === "maxMin")
+        result.reverse = true;
+    const min = readNumber(get(axis, "c:scaling.c:min.a$.val") ?? get(axis, "scaling.min.a$.val"));
+    if (typeof min === "number")
+        result.min = min;
+    const max = readNumber(get(axis, "c:scaling.c:max.a$.val") ?? get(axis, "scaling.max.a$.val"));
+    if (typeof max === "number")
+        result.max = max;
+    // <c:delete val="1"/> hides the axis entirely.
+    const deleted = readBoolean(get(axis, "c:delete.a$.val") ?? get(axis, "delete.a$.val"));
+    if (deleted)
+        result.visible = false;
+    // <c:majorGridlines/> presence == show. Empty element is sufficient.
+    const majorGridlines = get(axis, "c:majorGridlines") ?? get(axis, "majorGridlines");
+    if (majorGridlines !== undefined)
+        result.showMajorGridlines = true;
+    // <c:txPr> — axis tick-label font/color. Without this we'd inherit
+    // the renderer's theme default (near-black) and lose the authored
+    // color (e.g. BEP.xlsx X axis = #14325A, Y axis = #F0621C).
+    const textFormat = extractTextProperties(get(axis, "c:txPr") ?? get(axis, "txPr"));
+    if (textFormat)
+        result.textFormat = textFormat;
+    return Object.keys(result).length ? result : undefined;
+}
+export function extractAxisOptions(plotArea) {
+    const valAx = get(plotArea, "c:valAx") ?? get(plotArea, "valAx");
+    const catAx = get(plotArea, "c:catAx") ?? get(plotArea, "catAx");
+    // Some chart types use <c:dateAx>; treat as category for our purposes.
+    const dateAx = get(plotArea, "c:dateAx") ?? get(plotArea, "dateAx");
+    const valAxes = Array.isArray(valAx) ? valAx : valAx ? [valAx] : [];
+    return {
+        valueAxisOptions: readAxis(valAxes[0]),
+        secondaryValueAxisOptions: valAxes.length > 1 ? readAxis(valAxes[1]) : undefined,
+        categoryAxisOptions: readAxis((Array.isArray(catAx) ? catAx[0] : catAx) ??
+            (Array.isArray(dateAx) ? dateAx[0] : dateAx)),
+    };
+}
+/**
+ * Pie-of-pie / bar-of-pie — extract the of-pie layout fields from
+ * `<c:ofPieChart>`. Returns undefined for plain pies. `splitType`
+ * maps the OOXML tokens (`pos`/`val`/`percent`) to the spec vocabulary;
+ * `auto` and `cust` (custom point assignment, carried in `<c:custSplit>`
+ * which the spec cannot represent) are omitted so the renderer applies
+ * Excel's default rule (position, last 3 values).
+ */
+export function extractOfPieOptions(plotArea) {
+    const ofPie = getWithFallback(plotArea, ["c:ofPieChart", "ofPieChart"]);
+    if (!ofPie)
+        return undefined;
+    const typeRaw = get(ofPie, "c:ofPieType.a$.val") ?? get(ofPie, "ofPieType.a$.val");
+    const ofPieType = typeRaw === "bar" ? "bar" : "pie";
+    const splitRaw = get(ofPie, "c:splitType.a$.val") ?? get(ofPie, "splitType.a$.val");
+    const splitType = splitRaw === "pos"
+        ? "position"
+        : splitRaw === "val"
+            ? "value"
+            : splitRaw === "percent"
+                ? "percent"
+                : undefined;
+    const splitPos = readNumber(get(ofPie, "c:splitPos.a$.val") ?? get(ofPie, "splitPos.a$.val"));
+    const secondPieSize = readNumber(get(ofPie, "c:secondPieSize.a$.val") ??
+        get(ofPie, "secondPieSize.a$.val"));
+    return {
+        ofPieType,
+        ...(splitType ? { splitType } : {}),
+        ...(typeof splitPos === "number" ? { splitPos } : {}),
+        ...(typeof secondPieSize === "number" ? { secondPieSize } : {}),
+    };
+}
+function extractDoughnutHoleSize(plotArea) {
+    // <c:doughnutChart><c:holeSize val="50"/> — value is the inner radius
+    // as a percentage of the chart radius (0-90). We normalize to a 0-1
+    // fraction so renderers can use it without knowing the spec.
+    const holeSize = readNumber(get(plotArea, "c:doughnutChart.c:holeSize.a$.val") ??
+        get(plotArea, "doughnutChart.holeSize.a$.val"));
+    if (typeof holeSize !== "number")
+        return undefined;
+    return Math.min(0.9, Math.max(0, holeSize / 100));
+}
+// -------------------------- Phase 5.2 helpers --------------------------
+const mapTrendlineType = (val) => {
+    switch (val) {
+        case "exp":
+            return "exp";
+        case "log":
+            return "log";
+        case "poly":
+            return "poly";
+        case "power":
+            return "power";
+        case "movingAvg":
+            return "movingAvg";
+        case "linear":
+        default:
+            return "linear";
+    }
+};
+function extractTrendlines(ser) {
+    // <c:trendline> can appear multiple times under a single series; the
+    // parser may surface either an array or a single object.
+    const raw = get(ser, "c:trendline") ?? get(ser, "trendline");
+    if (!raw)
+        return undefined;
+    const list = Array.isArray(raw) ? raw : [raw];
+    const results = [];
+    for (const t of list) {
+        const type = mapTrendlineType(get(t, "c:trendlineType.a$.val") ?? get(t, "trendlineType.a$.val"));
+        const order = readNumber(get(t, "c:order.a$.val") ?? get(t, "order.a$.val"));
+        const period = readNumber(get(t, "c:period.a$.val") ?? get(t, "period.a$.val"));
+        const name = get(t, "c:name.t$") ?? get(t, "name.t$") ?? get(t, "c:name") ?? get(t, "name");
+        const showEquation = readBoolean(get(t, "c:dispEq.a$.val") ?? get(t, "dispEq.a$.val"));
+        const showRSquared = readBoolean(get(t, "c:dispRSqr.a$.val") ?? get(t, "dispRSqr.a$.val"));
+        const forecastForward = readNumber(get(t, "c:forward.a$.val") ?? get(t, "forward.a$.val"));
+        const forecastBackward = readNumber(get(t, "c:backward.a$.val") ?? get(t, "backward.a$.val"));
+        const entry = { type };
+        if (typeof order === "number")
+            entry.order = order;
+        if (typeof period === "number")
+            entry.period = period;
+        if (typeof name === "string" && name)
+            entry.name = name;
+        if (showEquation)
+            entry.showEquation = true;
+        if (showRSquared)
+            entry.showRSquared = true;
+        if (typeof forecastForward === "number")
+            entry.forecastForward = forecastForward;
+        if (typeof forecastBackward === "number")
+            entry.forecastBackward = forecastBackward;
+        results.push(entry);
+    }
+    return results;
+}
+function extractErrorBars(ser, hostSheetId, resolveSheetId) {
+    const raw = get(ser, "c:errBars") ?? get(ser, "errBars");
+    if (!raw)
+        return undefined;
+    const direction = get(raw, "c:errDir.a$.val") ?? get(raw, "errDir.a$.val");
+    const barType = get(raw, "c:errBarType.a$.val") ?? get(raw, "errBarType.a$.val");
+    const valTypeVal = get(raw, "c:errValType.a$.val") ?? get(raw, "errValType.a$.val");
+    const value = readNumber(get(raw, "c:val.a$.val") ?? get(raw, "val.a$.val"));
+    const noEndCap = readBoolean(get(raw, "c:noEndCap.a$.val") ?? get(raw, "noEndCap.a$.val"));
+    const result = {};
+    if (direction === "x" || direction === "y")
+        result.direction = direction;
+    if (barType === "both" || barType === "plus" || barType === "minus") {
+        result.barType = barType;
+    }
+    if (valTypeVal === "fixedVal" ||
+        valTypeVal === "percentage" ||
+        valTypeVal === "stdDev" ||
+        valTypeVal === "stdErr" ||
+        valTypeVal === "cust") {
+        result.valueType = valTypeVal === "cust" ? "custom" : valTypeVal;
+    }
+    if (typeof value === "number")
+        result.value = value;
+    if (noEndCap)
+        result.noEndCap = true;
+    // Custom error bars carry per-point magnitudes in worksheet ranges —
+    // `<c:plus>/<c:minus>` each hold a `<c:numRef><c:f>` reference.
+    if (result.valueType === "custom") {
+        const plusRef = getWithFallback(raw, [
+            "c:plus.c:numRef.c:f",
+            "c:plus.c:numRef.c:f.t$",
+            "plus.numRef.f",
+            "plus.numRef.f.t$",
+        ]);
+        const minusRef = getWithFallback(raw, [
+            "c:minus.c:numRef.c:f",
+            "c:minus.c:numRef.c:f.t$",
+            "minus.numRef.f",
+            "minus.numRef.f.t$",
+        ]);
+        if (plusRef) {
+            const plusSources = resolveSourcesFromRef(plusRef, hostSheetId, resolveSheetId);
+            if (plusSources.length)
+                result.plusRange = plusSources[0];
+        }
+        if (minusRef) {
+            const minusSources = resolveSourcesFromRef(minusRef, hostSheetId, resolveSheetId);
+            if (minusSources.length)
+                result.minusRange = minusSources[0];
+        }
+    }
+    return Object.keys(result).length ? result : undefined;
+}
+function extractRadarStyle(plotArea) {
+    const val = get(plotArea, "c:radarChart.c:radarStyle.a$.val") ??
+        get(plotArea, "radarChart.radarStyle.a$.val");
+    if (val === "standard" || val === "marker" || val === "filled")
+        return val;
+    return undefined;
+}