@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/types/modules/excel/types.d.ts

@@ -379,6 +379,78 @@ export interface Comment {
     margins?: Partial<CommentMargins>;
     protection?: Partial<CommentProtection>;
     editAs?: CommentEditAs;
+    /**
+     * Office 365 threaded-comment conversation anchored at the same
+     * cell. When present, Excel surfaces the modern reply UI; the
+     * classic VML note still renders as a fallback for older viewers.
+     *
+     * The first entry in the list is the top-level comment; subsequent
+     * entries with `parentId === first.id` are replies to it. Nested
+     * threads beyond two levels are not supported by Excel itself.
+     */
+    threadedComments?: ThreadedComment[];
+}
+/**
+ * A single entry in a threaded-comment conversation
+ * (`xl/threadedComments/threadedComment{N}.xml` →
+ * `<threadedComment ref="…" personId="…" id="…" parentId="…">`).
+ *
+ * `id` is a GUID-braced string Excel expects to uniquely identify the
+ * comment within the sheet; callers may omit it and let the writer
+ * synthesise one. `personId` must reference an entry in the
+ * workbook-level {@link ThreadedCommentPerson} list — the writer
+ * enforces this by adding any dangling `personId` to the list with a
+ * placeholder displayName.
+ */
+export interface ThreadedComment {
+    /** `{GUID}`-style id; auto-generated if absent. */
+    id?: string;
+    /**
+     * Id of the parent comment when this entry is a reply. Absent for
+     * top-level comments.
+     */
+    parentId?: string;
+    /** Reference to the author in the workbook persons list. */
+    personId: string;
+    /** Creation timestamp as an ISO-8601 string. */
+    date?: string;
+    /** Plain-text body. @mentions are expressed separately via {@link mentions}. */
+    text: string;
+    /**
+     * Structured `@mention` markers inside `text`. `startIndex`/`length`
+     * point at the substring Excel shows as a clickable mention.
+     */
+    mentions?: ThreadedCommentMention[];
+    /**
+     * Whether Excel marks this comment as "resolved". Corresponds to
+     * `done="1"` on the commentExt element. When undefined, Excel treats
+     * the thread as open.
+     */
+    done?: boolean;
+}
+export interface ThreadedCommentMention {
+    mentionId?: string;
+    mentionPersonId: string;
+    startIndex: number;
+    length: number;
+}
+/**
+ * Workbook-level person directory referenced by threaded comments.
+ * Written as `xl/persons/person.xml`; one `<person>` element per
+ * unique commenter.
+ */
+export interface ThreadedCommentPerson {
+    /** `{GUID}`-style id referenced by `threadedComment/@personId`. */
+    id: string;
+    /** Display name shown in the UI (e.g. "Jane Doe"). */
+    displayName: string;
+    /** Provider user id (e.g. "jane@example.com", "S-1-5-…"). */
+    userId?: string;
+    /**
+     * Identity provider — "AD" (Active Directory), "PeoplePicker",
+     * "None". Excel preserves unknown values verbatim.
+     */
+    providerId?: string;
 }
 export type DataValidationOperator = "between" | "notBetween" | "equal" | "notEqual" | "greaterThan" | "lessThan" | "greaterThanOrEqual" | "lessThanOrEqual";
 /** Base properties shared by all data validation types */

package/dist/types/modules/excel/utils/address.d.ts

@@ -74,3 +74,21 @@ export declare function decodeRange(range: string): SheetRange;
  */
 export declare function encodeRange(range: SheetRange): string;
 export declare function encodeRange(start: CellAddress, end: CellAddress): string;
+/**
+ * Excel allows unquoted sheet names only when they consist entirely of
+ * ASCII letters, digits, and underscores *and* do not start with a digit.
+ * Any sheet name with a space, dot, comma, bracket, `&`, CJK character,
+ * or any other non-trivial symbol must be wrapped in single quotes, with
+ * existing single quotes doubled.
+ *
+ * Shared helper so chart-api, pivot-chart, cache-populator, and the XForm
+ * layer all agree on the rule — before this was unified, three callers
+ * in the chart module used three different regexes, producing divergent
+ * formula strings for sheet names with punctuation.
+ *
+ * @example quoteSheetName("Sheet1") // "Sheet1"
+ * @example quoteSheetName("My Sheet") // "'My Sheet'"
+ * @example quoteSheetName("It's Fine") // "'It''s Fine'"
+ * @example quoteSheetName("2023 Data") // "'2023 Data'" (leading digit → quoted)
+ */
+export declare function quoteSheetName(sheetName: string): string;

package/dist/types/modules/excel/utils/guid.d.ts

@@ -0,0 +1,15 @@
+/**
+ * GUID helpers for OOXML.
+ *
+ * Office parts that need stable cross-reference ids (threaded comments,
+ * chart uniqueIds, slicer caches, …) use the canonical Microsoft
+ * `{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}` format — 32 uppercase hex
+ * characters split into 8-4-4-4-12 groups, surrounded by braces.
+ *
+ * `synthGuid()` returns an RFC-4122 version-4-compatible value suitable
+ * for those callers. We don't use `crypto.randomUUID()` directly because
+ * it isn't available in every supported runtime (older Node without
+ * `node:crypto` globals); `Math.random` is good enough for uniqueness
+ * within a single workbook, which is the only thing Office cares about.
+ */
+export declare function synthGuid(): string;

package/dist/types/modules/excel/utils/ooxml-paths.d.ts

@@ -21,6 +21,14 @@ export declare function getThemeNameFromPath(path: string): string | undefined;
 export declare function isBinaryEntryPath(path: string): boolean;
 export declare function getDrawingNameFromPath(path: string): string | undefined;
 export declare function getDrawingNameFromRelsPath(path: string): string | undefined;
+/**
+ * Canonical filename stem for a chart-overlay drawing part — used by
+ * the reader to recognise `xl/drawings/chartUserShapeN.xml` entries
+ * and stash their bytes for post-load reconciliation onto the owning
+ * chart. Returns `undefined` for any other path, including regular
+ * worksheet drawings (those go through {@link getDrawingNameFromPath}).
+ */
+export declare function getChartUserShapesNameFromPath(path: string): string | undefined;
 export declare function getVmlDrawingNameFromPath(path: string): string | undefined;
 export declare function getVmlDrawingHFNameFromPath(path: string): string | undefined;
 /**
@@ -52,6 +60,22 @@ export declare function worksheetRelsPath(sheetId: number | string): string;
 export declare function worksheetRelTarget(sheetId: number | string): string;
 export declare function commentsPath(sheetId: number | string): string;
 export declare function commentsPathFromName(commentName: string): string;
+/**
+ * Modern Office 365 "threaded comments" — separate from classic VML
+ * comments. Each worksheet that uses threaded comments has its own
+ * `xl/threadedComments/threadedComment{N}.xml` part alongside the
+ * legacy `xl/comments{N}.xml` (classic comments carry a fallback text
+ * representation, threaded comments carry the conversation tree).
+ */
+export declare function threadedCommentsPath(sheetId: number | string): string;
+export declare function threadedCommentsPathFromName(name: string): string;
+/**
+ * Modern Office 365 "persons" list — the directory of commenters
+ * referenced by `threadedComment/@personId`. Workbook-level single
+ * part (`xl/persons/person.xml` is the conventional filename for the
+ * primary, rarely-duplicated list).
+ */
+export declare function personsPath(): string;
 export declare function vmlDrawingPath(sheetId: number | string): string;
 export declare function vmlDrawingHFPath(sheetId: number | string): string;
 export declare function vmlDrawingHFRelsPath(sheetId: number | string): string;
@@ -89,6 +113,50 @@ export declare function pivotTableRelTargetFromWorksheet(n: number | string): st
 export declare function tableRelTargetFromWorksheet(target: string): string;
 export declare function mediaRelTargetFromRels(filename: string): string;
 export declare function ctrlPropPath(id: number | string): string;
+export declare function getChartNumberFromPath(path: string): number | undefined;
+export declare function getChartNumberFromRelsPath(path: string): number | undefined;
+export declare function getChartStyleNumberFromPath(path: string): number | undefined;
+export declare function getChartColorsNumberFromPath(path: string): number | undefined;
+export declare function getChartExStyleNumberFromPath(path: string): number | undefined;
+export declare function getChartExColorsNumberFromPath(path: string): number | undefined;
+export declare function chartPath(n: number | string): string;
+export declare function chartRelsPath(n: number | string): string;
+export declare function chartStylePath(n: number | string): string;
+export declare function chartColorsPath(n: number | string): string;
+export declare function chartExStylePath(n: number | string): string;
+export declare function chartExColorsPath(n: number | string): string;
+export declare function chartRelTargetFromDrawing(n: number | string): string;
+/**
+ * Path of the DrawingML overlay part backing a chart's `c:userShapes`
+ * reference. Placed under `xl/drawings/` with a `chartUserShape` prefix
+ * (rather than sharing the regular `drawingN` pool) so the writer can
+ * allocate it by chart number without colliding with worksheet
+ * drawings. Excel itself is indifferent to the part path — only the
+ * rel target matters — so files loaded with a different original
+ * path are renamed on write.
+ */
+export declare function chartUserShapesPath(n: number | string): string;
+/**
+ * Target path emitted inside `xl/charts/_rels/chartN.xml.rels` for the
+ * user-shapes drawing part. Resolved relative to the rels file's
+ * base directory (`xl/charts/`).
+ */
+export declare function chartUserShapesRelTarget(n: number | string): string;
+export declare function chartStyleRelTarget(n: number | string): string;
+export declare function chartColorsRelTarget(n: number | string): string;
+export declare function chartExStyleRelTarget(n: number | string): string;
+export declare function chartExColorsRelTarget(n: number | string): string;
+export declare function isChartPath(path: string): boolean;
+export declare function isChartStylePath(path: string): boolean;
+export declare function isChartColorsPath(path: string): boolean;
+export declare function isChartRelsPath(path: string): boolean;
+export declare function getChartExNumberFromPath(path: string): number | undefined;
+export declare function getChartExNumberFromRelsPath(path: string): number | undefined;
+export declare function chartExPath(n: number | string): string;
+export declare function chartExRelsPath(n: number | string): string;
+export declare function chartExRelTargetFromDrawing(n: number | string): string;
+export declare function isChartExPath(path: string): boolean;
+export declare function isChartExRelsPath(path: string): boolean;
 export declare function ctrlPropRelTargetFromWorksheet(id: number | string): string;
 /**
  * Resolve a relationship Target (relative or absolute) to a normalized zip path.
@@ -101,3 +169,9 @@ export declare function ctrlPropRelTargetFromWorksheet(id: number | string): str
  * @param target   The raw Target value from the .rels file
  */
 export declare function resolveRelTarget(baseDir: string, target: string): string;
+export declare function getChartsheetNoFromPath(path: string): number | undefined;
+export declare function getChartsheetNoFromRelsPath(path: string): number | undefined;
+export declare function chartsheetPath(n: number | string): string;
+export declare function chartsheetRelsPath(n: number | string): string;
+export declare function isChartsheetPath(path: string): boolean;
+export declare function isChartsheetRelsPath(path: string): boolean;

package/dist/types/modules/excel/utils/ooxml-validator/check-chart-sidecar.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ChartEx sidecar completeness check.
+ *
+ * Every ChartEx `xl/charts/chartExN.xml` MUST ship with a chartStyle
+ * sidecar (`xl/charts/styleN.xml` or `xl/charts/styleExN.xml`) and a
+ * chartColorStyle sidecar (`xl/charts/colorsN.xml` or
+ * `xl/charts/colorsExN.xml`), linked from `chartExN.xml.rels`. Without
+ * them Excel 2016+ discards the chartEx on load ("Removed Part:
+ * /xl/drawings/drawingN.xml (Drawing shape)").
+ *
+ * Both sidecars are STUB-REJECTED **for chartEx** — an id-only
+ * skeleton such as `<cs:chartStyle id="395"/>` (no child elements)
+ * makes Excel treat the sidecar as malformed and drop the parent
+ * chartEx + drawing. Excel authoring tools emit the FULL content: ~40
+ * child elements for chartStyle (axisTitle, dataPoint, dataLabel, …)
+ * and 6 `schemeClr` entries each with 9 `variation` siblings for
+ * chartColorStyle.
+ *
+ * CLASSIC charts (`xl/charts/chartN.xml`) can share the chartStyle
+ * namespace but Excel is lenient there — classic chart style stubs
+ * are accepted. We therefore only enforce the no-stub rule on
+ * sidecars **referenced by a `chartExN.xml` part** via its rels.
+ *
+ * The precise content is too intricate to validate without baking
+ * ~1500 lines of template XML into this module. Instead we detect the
+ * two high-signal stub patterns:
+ *
+ *   - chartStyle root element has zero element children (pure stub).
+ *   - chartColorStyle root element has zero element children (pure stub).
+ *
+ * A rich sidecar trivially has dozens of children so the zero-child
+ * case is a strong writer-bug signature.
+ */
+import { type ValidationContext } from "./context.js";
+export declare function checkChartSidecars(ctx: ValidationContext): void;

package/dist/types/modules/excel/utils/ooxml-validator/check-chart.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Chart / chartEx internal structure check.
+ *
+ * Classic charts (`xl/charts/chartN.xml`) must contain both `c:chart` and
+ * `c:plotArea`. ChartEx charts must contain `cx:chart`, `cx:plotArea`
+ * and at least one `cx:series`; series must carry `layoutId` and their
+ * `dataId`/`axisId` back-references must resolve inside the chart.
+ * `cx:externalData` nodes must refer to a declared relationship.
+ *
+ * In addition we catch five chartEx schema-violation patterns that
+ * cause Excel 2016+ to drop the whole chartEx part with "Removed Part:
+ * /xl/drawings/drawingN.xml (Drawing shape)":
+ *
+ *   - `<cx:series>` with more than one `<cx:dataId>` child
+ *     (`CT_Series/dataId` has `maxOccurs="1"`; multi-dim series must
+ *     use a single `<cx:data>` wrapper with multiple strDim/numDim).
+ *   - `<cx:axisId>N</cx:axisId>`, `<cx:dataId>N</cx:dataId>`,
+ *     `<cx:binCount>N</cx:binCount>`, `<cx:binSize>N</cx:binSize>`
+ *     emitted as text content instead of `val="N"` attribute. The
+ *     underlying types are `CT_UnsignedInteger`/`CT_Double`, which
+ *     Excel's strict loader only accepts via the attribute form.
+ *   - `<cx:auto/>` element anywhere in the chartEx. Auto binning is
+ *     expressed by the ABSENCE of `binSize`/`binCount`, not a
+ *     dedicated `<cx:auto/>` tag. The tag is schema-invalid.
+ *   - `<cx:paretoLine>` child of `<cx:layoutPr>`. Not in the
+ *     CT_SeriesLayoutProperties schema. A real pareto chart adds a
+ *     second series with `layoutId="paretoLine"`.
+ *   - `<cx:title>` with a direct `<cx:layout>` child. Title layout
+ *     belongs in `extLst`-based extensions.
+ */
+import type { ValidationContext } from "./context.js";
+export declare function checkChart(ctx: ValidationContext): void;

package/dist/types/modules/excel/utils/ooxml-validator/check-chartsheet.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Chartsheet structure check.
+ *
+ * A chartsheet (`xl/chartsheets/sheetN.xml`) must contain a `<drawing>`
+ * reference — the chart itself is always in the linked drawing part.
+ * Without it, Excel shows an empty chart sheet.
+ */
+import type { ValidationContext } from "./context.js";
+export declare function checkChartsheet(ctx: ValidationContext): void;

package/dist/types/modules/excel/utils/ooxml-validator/check-content-types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Content-types check.
+ *
+ * OPC requires every part in the package to be resolvable to a
+ * content-type via either a `<Default Extension=...>` entry or a
+ * `<Override PartName=...>` entry. Excel rejects packages where this
+ * mapping has gaps — the classic "repairable content" error.
+ *
+ * Beyond the OPC-mandatory rules, we also enforce Microsoft's
+ * well-known part→type expectations for the common OOXML part layouts
+ * (chart, pivot, chartsheet, drawing, etc.). A wrong content-type on
+ * these parts is one of the top causes of "Excel cannot open" errors
+ * because Excel uses the type string to route parsing.
+ */
+import type { ValidationContext } from "./context.js";
+export declare function checkContentTypes(ctx: ValidationContext): void;

package/dist/types/modules/excel/utils/ooxml-validator/check-drawing.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Drawing part structure check.
+ *
+ * When a drawing file contains `<xdr:graphicFrame>` nodes but neither a
+ * classic `<c:chart>` nor a chartEx `<cx:chart>` reference inside them,
+ * the graphic frame is dangling — Excel shows a placeholder or drops the
+ * frame on load.
+ *
+ * We also scan anchor coordinates: every anchor must have `from` and
+ * `to` child elements, and EMU values (`x`, `y`, `cx`, `cy`,
+ * `colOff`, `rowOff`) when present must parse as finite non-negative
+ * numbers. Excel rejects anchors with NaN coordinates outright.
+ *
+ * Finally we enforce the ChartEx drawing-wrapper invariants that
+ * trigger "Removed Part: /xl/drawings/drawingN.xml (Drawing shape)"
+ * in production Excel logs:
+ *
+ *   - Any `<cx:chart>` reference MUST live inside an
+ *     `<mc:AlternateContent>` block. The Microsoft ChartEx schema was
+ *     never part of the base OOXML spec, so Excel's strict loader
+ *     requires MC substitution so legacy readers see a fallback shape.
+ *   - The `<mc:Fallback>` MUST be non-empty. An empty Fallback
+ *     collapses the anchor to nothing on clients that take that
+ *     branch, and Excel's strict loader has been observed to reject
+ *     the drawing even on the Choice branch when it sees the
+ *     degenerate Fallback.
+ *   - `<mc:AlternateContent>` lives INSIDE the `<xdr:twoCellAnchor>`
+ *     shape slot (between `<xdr:to>` and `<xdr:clientData>`), NOT
+ *     around the whole anchor. Wrapping the entire anchor duplicates
+ *     `<xdr:from>`/`<xdr:to>` across Choice and Fallback, which Excel
+ *     rejects even though MC substitution permits it in theory.
+ */
+import type { ValidationContext } from "./context.js";
+export declare function checkDrawing(ctx: ValidationContext): void;

package/dist/types/modules/excel/utils/ooxml-validator/check-pivot.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Pivot table & pivot cache check.
+ *
+ * Each `xl/pivotTables/pivotTableN.xml` declares a `cacheId` that must be
+ * registered in the workbook's `<pivotCaches>` list; the cache in turn
+ * must back a live pivotCacheDefinition/pivotCacheRecords pair.
+ *
+ * We do a lightweight cross-reference check: (a) every pivot table
+ * advertises a cacheId that resolves to a `<pivotCache>` entry in
+ * workbook.xml, and (b) each referenced pivotCacheDefinition's rels point
+ * at a pivotCacheRecords file that actually exists.
+ */
+import type { ValidationContext } from "./context.js";
+export declare function checkPivot(ctx: ValidationContext): void;

package/dist/types/modules/excel/utils/ooxml-validator/check-relationships.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Relationships check.
+ *
+ * For every `.rels` file in the package we verify:
+ *   - The root element is `<Relationships>` and children are `<Relationship>`.
+ *   - Each rel has `Id`, `Type`, and `Target` attributes.
+ *   - Relationship `Id` values are unique within the same rels file.
+ *   - Non-external targets resolve to files that exist inside the package.
+ *   - Resolved targets stay inside the package root (no `..` escape).
+ *   - For well-known rel types, the resolved target matches the expected
+ *     part-name pattern (e.g. a `Type=...relationships/chart` rel must
+ *     point at `xl/charts/chartN.xml`).
+ *   - Every non-root rels file has a corresponding source part in the zip.
+ *   - The package root rels include an officeDocument rel to `xl/workbook.xml`.
+ */
+import type { ValidationContext } from "./context.js";
+export declare function checkRootRelationships(ctx: ValidationContext): void;
+export declare function checkRelationships(ctx: ValidationContext): void;

package/dist/types/modules/excel/utils/ooxml-validator/check-structure.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Package structure check.
+ *
+ * Verifies the package contains the four OPC-mandatory parts (every xlsx
+ * must have these to be considered an Open Packaging Convention file) and
+ * that every XML-like part is syntactically well-formed.
+ *
+ * XML well-formedness is the broadest reachable check — it catches
+ * unclosed tags, bad escapes, and invalid entities that would cause Excel
+ * to repair-or-reject the whole package. We parse via DOM (which
+ * internally delegates to SAX) so that subsequent DOM-based checkers hit
+ * the same cached result.
+ */
+import type { ValidationContext } from "./context.js";
+export declare function checkStructure(ctx: ValidationContext): void;
+/**
+ * Walk every XML-like entry and parse it to surface malformed-XML
+ * problems. Leverages the context cache so DOM-based checkers that run
+ * afterwards do not re-parse.
+ */
+export declare function checkXmlWellFormed(ctx: ValidationContext): void;

package/dist/types/modules/excel/utils/ooxml-validator/check-styles.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Styles table integrity.
+ *
+ * Every xf in `cellXfs` references indices into `numFmts`, `fonts`,
+ * `fills`, `borders`. Out-of-bounds references produce style corruption
+ * on load (Excel falls back to the default style silently, so this is a
+ * warning-severity check — it's a strong signal of a broken writer but
+ * not a hard "Excel cannot open" issue).
+ *
+ * `numFmts` uses numeric IDs, including ~100 built-in IDs < 164 that are
+ * never declared. We only flag ids >= 164 that have no matching numFmt
+ * entry.
+ */
+import type { ValidationContext } from "./context.js";
+export declare function checkStyles(ctx: ValidationContext): void;

package/dist/types/modules/excel/utils/ooxml-validator/check-table.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Table part check.
+ *
+ * Three real-world "Removed Records: Table from /xl/tables/tableN.xml"
+ * patterns that cause Excel to drop the entire table on open:
+ *
+ *   1. **Redundant per-column `<filterColumn>`.** The writer used to
+ *      emit a bare `<filterColumn colId="N" hiddenButton="1"/>` for
+ *      every column in the table. The schema accepts it, but Excel's
+ *      loader interprets a fully-hidden autoFilter on a live table as
+ *      inconsistent and drops the table to recover.
+ *
+ *   2. **`<totalsRowFormula>` paired with a built-in
+ *      `totalsRowFunction`.** The schema allows the child only when
+ *      the function is `"custom"` (or absent). For any of `sum`,
+ *      `average`, `count`, `countNums`, `max`, `min`, `stdDev`,
+ *      `var` Excel generates the SUBTOTAL formula itself and rejects
+ *      the table if we pre-emit one.
+ *
+ *   3. **autoFilter range covering the totals row.** When
+ *      `totalsRowCount="1"` is set on the `<table>`, the autoFilter
+ *      range must stop one row above the totals row. Filtering the
+ *      totals row itself is semantically invalid and Excel rejects
+ *      the table.
+ *
+ * These are some of the most common "Excel cannot open" symptoms in
+ * production xlsx from other tooling too — catching them up front is a
+ * high-value check.
+ */
+import type { ValidationContext } from "./context.js";
+export declare function checkTables(ctx: ValidationContext): void;

package/dist/types/modules/excel/utils/ooxml-validator/check-workbook.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Workbook-level check.
+ *
+ * Reads `xl/workbook.xml` as DOM (replacing the previous regex-based
+ * approach, which missed namespaced elements like `<x:sheet>`) and walks
+ * every `<sheet>` declaration to verify:
+ *
+ *   - `sheetId` uniqueness (OOXML requires globally unique sheet IDs).
+ *   - `r:id` uniqueness and pointing to a worksheet-type relationship.
+ *   - `name` attribute presence and Excel's name constraints:
+ *       · 1–31 characters
+ *       · No characters in `\ / ? * [ ] :`
+ *       · Not repeated case-insensitively
+ *   - CT_Workbook child element ordering (ECMA-376 Part 1 §18.2.27).
+ *     Excel rejects files whose direct children of `<workbook>` violate
+ *     the XSD sequence order.
+ */
+import type { ValidationContext } from "./context.js";
+export declare function checkWorkbook(ctx: ValidationContext): void;

package/dist/types/modules/excel/utils/ooxml-validator/check-worksheet.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Worksheet check — the largest and most important part of the validator.
+ *
+ * Covers four new structural checks beyond the original wiring check:
+ *   1. **Child element ordering** — `<worksheet>` children must appear in
+ *      the ECMA-376 canonical order. Excel is known to reject files with
+ *      out-of-order children; this is a top cause of "Excel needs to
+ *      repair" prompts.
+ *   2. **Cell `r="A1"` consistency** — every `<c r="…"/>` inside a
+ *      `<row r="N"/>` must decode to row `N` and to a column in
+ *      `[1, 16384]` (Excel's max column limit, XFD).
+ *   3. **Merge region overlap** — every `<mergeCell ref="A1:B2"/>` must
+ *      parse and no two merged ranges may overlap.
+ *   4. **Style / SST index bounds** — every `<c s="N"/>` must reference a
+ *      valid `cellXfs` index, and every `<c t="s"><v>N</v></c>` must
+ *      reference an existing `sharedStrings` index.
+ *
+ * Plus the legacy r:id wiring checks (controls, drawing, comments,
+ * hyperlink, tablePart, legacyDrawing) and the "controls without
+ * drawing" repair signal. The old "legacyDrawing-after-controls" kind is
+ * kept for backward compatibility — it is emitted in parallel with the
+ * generic `sheet-child-out-of-order` kind.
+ */
+import type { ValidationContext } from "./context.js";
+export declare function checkWorksheets(ctx: ValidationContext): void;

package/dist/types/modules/excel/utils/ooxml-validator/context.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Shared validation context.
+ *
+ * Checkers share XML parsing work through this context. Relationships,
+ * content types, and parsed XML DOMs are parsed at most once and cached.
+ * Every checker consumes from the same cache so they all see identical
+ * parse results (this matters for "rels malformed" propagation — the
+ * malformed entry is reported once, and every downstream checker simply
+ * sees the empty parse result).
+ */
+import type { ExtractedFile } from "../../../archive/unzip/extract.js";
+import type { XmlDocument, XmlElement } from "../../../xml/types.js";
+import type { Reporter } from "./reporter.js";
+export interface ContentTypesData {
+    defaults: Map<string, string>;
+    overrides: Map<string, string>;
+    /**
+     * `true` if the file was parsed as a `<Types>` root successfully.
+     * `false` if the file is missing, malformed or has an unexpected root.
+     */
+    parseOk: boolean;
+    /**
+     * Duplicate override part names encountered during parse. Emitted as
+     * problems by the content-types checker.
+     */
+    duplicateOverrides: string[];
+}
+export interface Relationship {
+    id: string;
+    type: string;
+    target: string;
+    targetMode?: string;
+}
+export interface RelsData {
+    rels: Relationship[];
+    byId: Map<string, Relationship>;
+    parseOk: boolean;
+    /**
+     * Raw rel entries that lacked Id/Type/Target attributes. Emitted
+     * separately so the rels checker can flag them without us dropping
+     * them from the data entirely.
+     */
+    malformedEntries: Array<{
+        missingId: boolean;
+        missingType: boolean;
+        missingTarget: boolean;
+        id?: string;
+        type?: string;
+    }>;
+}
+export declare class ValidationContext {
+    readonly entries: Map<string, ExtractedFile>;
+    readonly reporter: Reporter;
+    private readonly textCache;
+    private readonly domCache;
+    private readonly relsCache;
+    private contentTypes?;
+    constructor(entries: Map<string, ExtractedFile>, reporter: Reporter);
+    /** `true` if `path` points to a file (not a directory) in the package. */
+    has(path: string): boolean;
+    /** Iterate every file (skip directories). */
+    files(): IterableIterator<readonly [string, ExtractedFile]>;
+    /** Decode a part as UTF-8 text. Cached. */
+    readText(path: string): string | undefined;
+    /**
+     * Parse a part as XML DOM. Cached. Returns `undefined` if the part is
+     * missing or malformed. Callers that need to distinguish those cases
+     * should check `has(path)` first.
+     */
+    readDom(path: string, onMalformed?: (err: Error) => void): XmlDocument | undefined;
+    /**
+     * Read and cache the content-types table. On first call, parse
+     * `[Content_Types].xml`; subsequent calls return the cache.
+     * Reports malformed-XML problems via the reporter but never throws.
+     */
+    readContentTypes(): ContentTypesData;
+    /**
+     * Read and cache a relationships file. Every .rels in the package is
+     * parsed lazily on first request. Malformed files are reported once
+     * and return an empty relationships array.
+     */
+    readRels(relsPath: string): RelsData;
+}
+/** Get the root element of a DOM; returns undefined for missing DOM. */
+export declare function domRoot(dom: XmlDocument | undefined): XmlElement | undefined;

package/dist/types/modules/excel/utils/ooxml-validator/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Public entry point for the OOXML validator.
+ *
+ * Validates an xlsx package buffer against the OPC spec and Excel's
+ * known opening invariants. See `types.ts` for the full catalog of
+ * problem kinds.
+ *
+ * ```ts
+ * const report = await validateXlsxBuffer(await wb.xlsx.writeBuffer());
+ * if (!report.ok) {
+ *   console.error(report.problems);
+ * }
+ * ```
+ *
+ * The implementation is composed of independent checkers under
+ * `check-*.ts` — each can be unit-tested in isolation. The entry point
+ * orchestrates them with a shared `ValidationContext` that caches XML
+ * parsing across checks.
+ */
+import type { OoxmlOrderingProblemKind, OoxmlOrderingValidationProblem, OoxmlProblemKind, OoxmlProblemSeverity, OoxmlValidateOptions, OoxmlValidationProblem, OoxmlValidationReport, OoxmlValidationStats } from "./types.js";
+export type { OoxmlOrderingProblemKind, OoxmlOrderingValidationProblem, OoxmlProblemKind, OoxmlProblemSeverity, OoxmlValidateOptions, OoxmlValidationProblem, OoxmlValidationReport, OoxmlValidationStats };
+/**
+ * Validate an xlsx package. Returns a report with every detected
+ * problem; `ok === true` when no error-severity problems were found.
+ *
+ * This function never throws — malformed input is surfaced as a
+ * `xml-malformed` or similar problem kind. The only exception is if
+ * `extractAll` fails to unzip the buffer (not a valid ZIP at all), in
+ * which case the underlying archive error propagates.
+ */
+export declare function validateXlsxBuffer(xlsxBuffer: Uint8Array, options?: OoxmlValidateOptions): Promise<OoxmlValidationReport>;