@shbernal/ts-xlsx 1.0.0

package/dist/io/xlsx/images.d.ts

@@ -0,0 +1,34 @@
+import { type AnchorPoint, type Extent, type ImageAnchor, type ImageEditAs } from '../../core/image.ts';
+/** The content type for a media part's `<Default Extension>` entry in `[Content_Types].xml`. */
+export declare function imageContentType(extension: string): string;
+/** One image placed in a drawing: where it sits and the drawing-local relationship id that ties it
+ * to its media bytes. */
+export interface DrawingImage {
+    readonly anchor: ImageAnchor;
+    /** The `r:embed` id referencing this image's entry in the drawing's own `.rels`. */
+    readonly embedId: string;
+}
+/** The `xl/drawings/drawing{n}.xml` part: one anchor per image, two-cell or one-cell by its shape. */
+export declare function drawingXml(images: readonly DrawingImage[]): string;
+/** The drawing's `_rels/drawing{n}.xml.rels`: one image relationship per anchor, in `embedId` order
+ * (`rId1`, `rId2`, …), each pointing at the media part the anchor shows. */
+export declare function drawingRelsXml(mediaTargets: readonly string[]): string;
+/** An image anchor parsed from a drawing part, with the `r:embed` id that names its media. A two-cell
+ * anchor carries `to` (and may carry `editAs`); a one-cell anchor carries `ext` instead. */
+export interface ParsedImageAnchor {
+    readonly from: AnchorPoint;
+    readonly to?: AnchorPoint;
+    readonly ext?: Extent;
+    readonly editAs?: ImageEditAs;
+    readonly rotation?: number;
+    readonly embed: string;
+}
+/** Parse a drawing part into its image anchors (both `<xdr:twoCellAnchor>` and `<xdr:oneCellAnchor>`).
+ * Anchors that are not pictures (a chart, a shape) carry no `<a:blip r:embed>` and are skipped, so a
+ * mixed drawing yields only its images. */
+export declare function parseDrawing(xml: string): ParsedImageAnchor[];
+/** Whether a drawing part holds anchor content beyond plain pictures — a chart, shape, connector, or
+ * group. Excel packs every one of a sheet's anchors into a single drawing part, so a sheet with both a
+ * picture and a chart yields a mixed drawing; modeling only its pictures and re-serialising from them
+ * would drop the chart. The reader uses this to fall back to whole-drawing byte-preservation instead. */
+export declare function drawingHasUnmodeledContent(xml: string): boolean;

package/dist/io/xlsx/images.js

@@ -0,0 +1,218 @@
+// Anchored images on the wire: the `xl/drawings/drawing{n}.xml` part (a DrawingML two-cell anchor
+// per image), the drawing's own relationships to the `xl/media/` bytes, and the reader that turns a
+// drawing back into anchors. The image bytes themselves are opaque here — the writer copies them
+// verbatim into a media part and the reader hands them back untouched.
+import { isOneCellAnchor, } from "../../core/image.js";
+import { XML_DECLARATION } from "../../xml/xml.js";
+import { localName, parseXml } from "../../xml/xml-read.js";
+import { RELATIONSHIPS_NS } from "../opc/namespaces.js";
+import { relationship, relationshipsPart } from "../opc/rels.js";
+import { DRAWINGML_NS, XDR_NS } from "./namespaces.js";
+const IMAGE_REL_TYPE = `${RELATIONSHIPS_NS}/image`;
+// The content type Excel expects for each image kind, keyed by lower-case extension. An unlisted
+// extension falls back to `image/<ext>`, which is what a well-behaved consumer infers anyway.
+const IMAGE_CONTENT_TYPES = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    bmp: 'image/bmp',
+    tif: 'image/tiff',
+    tiff: 'image/tiff',
+    emf: 'image/x-emf',
+    wmf: 'image/x-wmf',
+    svg: 'image/svg+xml',
+};
+/** The content type for a media part's `<Default Extension>` entry in `[Content_Types].xml`. */
+export function imageContentType(extension) {
+    const ext = extension.toLowerCase();
+    return IMAGE_CONTENT_TYPES[ext] ?? `image/${ext}`;
+}
+/** The `xl/drawings/drawing{n}.xml` part: one anchor per image, two-cell or one-cell by its shape. */
+export function drawingXml(images) {
+    const anchors = images.map((image, i) => anchorXml(image, i + 1)).join('');
+    return (XML_DECLARATION +
+        `<xdr:wsDr xmlns:xdr="${XDR_NS}" xmlns:a="${DRAWINGML_NS}" xmlns:r="${RELATIONSHIPS_NS}">` +
+        anchors +
+        '</xdr:wsDr>');
+}
+function anchorXml(image, id) {
+    const { anchor } = image;
+    return isOneCellAnchor(anchor)
+        ? oneCellAnchorXml(anchor.from, anchor.ext, anchor.rotation, image.embedId, id)
+        : twoCellAnchorXml(anchor.from, anchor.to, anchor.editAs ?? 'oneCell', anchor.rotation, image.embedId, id);
+}
+// A picture anchored between two grid points. The geometry lives entirely in <xdr:from>/<xdr:to>, so
+// the picture carries no absolute <a:xfrm> — a zeroed one would override the anchor and collapse the
+// image to nothing in strict viewers (LibreOffice), while a non-zero one would fight the anchor. A
+// rotation is the one transform kept: it can't be derived from the anchor, so it rides a rot-only xfrm.
+function twoCellAnchorXml(from, to, editAs, rotation, embedId, id) {
+    return (`<xdr:twoCellAnchor editAs="${editAs}">` +
+        `<xdr:from>${anchorPointXml(from)}</xdr:from>` +
+        `<xdr:to>${anchorPointXml(to)}</xdr:to>` +
+        picXml(embedId, id, rotation) +
+        '<xdr:clientData/>' +
+        '</xdr:twoCellAnchor>');
+}
+// A picture pinned at one grid point with a fixed EMU extent. editAs is a two-cell-only attribute and
+// the schema forbids it here, so a one-cell anchor never carries one.
+function oneCellAnchorXml(from, ext, rotation, embedId, id) {
+    return ('<xdr:oneCellAnchor>' +
+        `<xdr:from>${anchorPointXml(from)}</xdr:from>` +
+        `<xdr:ext cx="${ext.cx}" cy="${ext.cy}"/>` +
+        picXml(embedId, id, rotation) +
+        '<xdr:clientData/>' +
+        '</xdr:oneCellAnchor>');
+}
+function picXml(embedId, id, rotation) {
+    const xfrm = rotation !== undefined ? `<a:xfrm rot="${rotation}"/>` : '';
+    return ('<xdr:pic>' +
+        `<xdr:nvPicPr><xdr:cNvPr id="${id}" name="Picture ${id}"/>` +
+        '<xdr:cNvPicPr><a:picLocks noChangeAspect="1"/></xdr:cNvPicPr></xdr:nvPicPr>' +
+        `<xdr:blipFill><a:blip r:embed="${embedId}"/>` +
+        '<a:stretch><a:fillRect/></a:stretch></xdr:blipFill>' +
+        `<xdr:spPr>${xfrm}<a:prstGeom prst="rect"><a:avLst/></a:prstGeom></xdr:spPr>` +
+        '</xdr:pic>');
+}
+function anchorPointXml(point) {
+    return (`<xdr:col>${point.col}</xdr:col><xdr:colOff>${point.colOff ?? 0}</xdr:colOff>` +
+        `<xdr:row>${point.row}</xdr:row><xdr:rowOff>${point.rowOff ?? 0}</xdr:rowOff>`);
+}
+/** The drawing's `_rels/drawing{n}.xml.rels`: one image relationship per anchor, in `embedId` order
+ * (`rId1`, `rId2`, …), each pointing at the media part the anchor shows. */
+export function drawingRelsXml(mediaTargets) {
+    return relationshipsPart(mediaTargets.map((target, i) => relationship(`rId${i + 1}`, IMAGE_REL_TYPE, target)));
+}
+function blankPoint() {
+    return { col: 0, row: 0, colOff: 0, rowOff: 0 };
+}
+const EDIT_AS = new Set(['oneCell', 'twoCell', 'absolute']);
+/** Parse a drawing part into its image anchors (both `<xdr:twoCellAnchor>` and `<xdr:oneCellAnchor>`).
+ * Anchors that are not pictures (a chart, a shape) carry no `<a:blip r:embed>` and are skipped, so a
+ * mixed drawing yields only its images. */
+export function parseDrawing(xml) {
+    const anchors = [];
+    let from = null;
+    let to = null;
+    let ext;
+    let editAs;
+    let rotation;
+    let embed;
+    // The point (<xdr:from> or <xdr:to>) whose coordinate children are currently streaming in.
+    let target = null;
+    // Depth inside <xdr:pic>, so the anchor-level <xdr:ext> is not confused with the <a:ext> nested in
+    // a picture's spPr transform (both have local name "ext").
+    let picDepth = 0;
+    // Which coordinate child is open, so its text lands on the right field; '' between children.
+    let coord = '';
+    let text = '';
+    parseXml(xml, {
+        onOpen(name, attrs) {
+            const local = localName(name);
+            if (local === 'twoCellAnchor' || local === 'oneCellAnchor') {
+                from = blankPoint();
+                to = local === 'twoCellAnchor' ? blankPoint() : null;
+                ext = undefined;
+                rotation = undefined;
+                embed = undefined;
+                const mode = attrs.editAs;
+                editAs = mode !== undefined && EDIT_AS.has(mode) ? mode : undefined;
+            }
+            else if (local === 'pic') {
+                picDepth++;
+            }
+            else if (local === 'xfrm' && picDepth > 0) {
+                // The picture's own rotation — the one spPr transform that can't be derived from the anchor.
+                const rot = Number(attrs.rot);
+                if (Number.isFinite(rot) && rot !== 0)
+                    rotation = rot;
+            }
+            else if (local === 'from') {
+                target = from;
+            }
+            else if (local === 'to') {
+                target = to;
+            }
+            else if (local === 'ext' && picDepth === 0) {
+                const cx = Number(attrs.cx);
+                const cy = Number(attrs.cy);
+                if (Number.isFinite(cx) && Number.isFinite(cy))
+                    ext = { cx, cy };
+            }
+            else if (local === 'blip') {
+                const value = attrs['r:embed'] ?? attrs.embed;
+                if (value !== undefined)
+                    embed = value;
+            }
+            else if (target !== null && COORDINATES.has(local)) {
+                coord = local;
+                text = '';
+            }
+        },
+        onText(chunk) {
+            if (coord !== '')
+                text += chunk;
+        },
+        onClose(name) {
+            const local = localName(name);
+            if (target !== null && coord === local && COORDINATES.has(local)) {
+                const value = Number(text);
+                if (Number.isFinite(value))
+                    setCoordinate(target, local, value);
+                coord = '';
+            }
+            else if (local === 'from' || local === 'to') {
+                target = null;
+            }
+            else if (local === 'pic') {
+                picDepth--;
+            }
+            else if (local === 'twoCellAnchor' || local === 'oneCellAnchor') {
+                if (from !== null && embed !== undefined) {
+                    const rot = rotation !== undefined ? { rotation } : {};
+                    if (to !== null) {
+                        const mode = editAs !== undefined ? { editAs } : {};
+                        anchors.push({ from: { ...from }, to: { ...to }, ...mode, ...rot, embed });
+                    }
+                    else if (ext !== undefined) {
+                        anchors.push({ from: { ...from }, ext, ...rot, embed });
+                    }
+                }
+                from = null;
+                to = null;
+                ext = undefined;
+            }
+        },
+    });
+    return anchors;
+}
+// Anchor content a drawing can hold that the image model does not interpret: a chart
+// (`<xdr:graphicFrame>`), a shape or text box (`<xdr:sp>`), a connector (`<xdr:cxnSp>`), or a group
+// (`<xdr:grpSp>`). A drawing carrying any of these is preserved whole rather than modeled, so it is
+// not re-serialised from its pictures alone (which would silently drop the chart/shape).
+const UNMODELED_DRAWING_CONTENT = new Set(['graphicFrame', 'sp', 'cxnSp', 'grpSp']);
+/** Whether a drawing part holds anchor content beyond plain pictures — a chart, shape, connector, or
+ * group. Excel packs every one of a sheet's anchors into a single drawing part, so a sheet with both a
+ * picture and a chart yields a mixed drawing; modeling only its pictures and re-serialising from them
+ * would drop the chart. The reader uses this to fall back to whole-drawing byte-preservation instead. */
+export function drawingHasUnmodeledContent(xml) {
+    let found = false;
+    parseXml(xml, {
+        onOpen(name) {
+            if (!found && UNMODELED_DRAWING_CONTENT.has(localName(name)))
+                found = true;
+        },
+    });
+    return found;
+}
+const COORDINATES = new Set(['col', 'colOff', 'row', 'rowOff']);
+function setCoordinate(point, coord, value) {
+    if (coord === 'col')
+        point.col = value;
+    else if (coord === 'colOff')
+        point.colOff = value;
+    else if (coord === 'row')
+        point.row = value;
+    else
+        point.rowOff = value;
+}

package/dist/io/xlsx/namespaces.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Canonical SpreadsheetML namespace URIs and well-known extension GUIDs.
+ *
+ * These are wire-format constants: Excel keys its parsing off the exact URI or
+ * GUID, so a producer must reproduce each one byte-for-byte. Centralizing them
+ * keeps the writer and reader from drifting apart and retires the
+ * `NS_MAIN`/`MAIN_NS`/`main` naming fork that had grown across the io modules.
+ *
+ * The package-level URIs (`.rels`, content types, the relationship vocabulary) describe the
+ * container rather than the spreadsheet inside it, and live in `../opc/namespaces.ts`.
+ */
+/**
+ * SpreadsheetML main namespace — the default `xmlns` of the workbook,
+ * worksheet, styles, sharedStrings, comments, table and pivot parts.
+ */
+export declare const SPREADSHEETML_NS = "http://schemas.openxmlformats.org/spreadsheetml/2006/main";
+/**
+ * Markup-compatibility namespace (`mc:`), whose `mc:Ignorable` attribute lists the prefixes a
+ * consumer that does not know them may skip rather than reject the part over.
+ */
+export declare const MARKUP_COMPATIBILITY_NS = "http://schemas.openxmlformats.org/markup-compatibility/2006";
+/**
+ * The 2014 revision namespace (`xr:`), which scopes the `xr:uid` Excel stamps on a comment. Declared
+ * `mc:Ignorable` wherever it appears, so a consumer that ignores it still reads the part.
+ */
+export declare const REVISION_NS = "http://schemas.microsoft.com/office/spreadsheetml/2014/revision";
+/**
+ * The 2018 threaded-comments namespace, shared by both parts of the feature — a sheet's
+ * `threadedComment{n}.xml` and the workbook's `person.xml`. Note the plural `threadedcomments`, all
+ * lower-case: Excel matches the URI exactly and reads neither part under any other spelling.
+ */
+export declare const THREADED_COMMENTS_NS = "http://schemas.microsoft.com/office/spreadsheetml/2018/threadedcomments";
+/** DrawingML shared graphics namespace (`a:`). */
+export declare const DRAWINGML_NS = "http://schemas.openxmlformats.org/drawingml/2006/main";
+/** Spreadsheet-drawing anchor namespace (`xdr:`) used by the worksheet drawing part. */
+export declare const XDR_NS = "http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing";
+/**
+ * The 2009 Microsoft extension namespace. `x14` scopes the feature elements
+ * Excel tucks inside `<ext>` blocks (conditional formatting, data validation,
+ * slicers); it is declared inline on those elements exactly as Excel writes
+ * them, so a worksheet root never needs an extra namespace declaration.
+ */
+export declare const X14_NS = "http://schemas.microsoft.com/office/spreadsheetml/2009/9/main";
+/** Scopes the `<xm:sqref>`/`<xm:f>` references the x14 feature elements carry. */
+export declare const XM_NS = "http://schemas.microsoft.com/office/excel/2006/main";
+/**
+ * Well-known `<ext uri=…>` GUIDs. Each `<ext>` block is opaque to a consumer
+ * that does not recognize its GUID, so a producer must emit these exact values
+ * for Excel to rediscover the feature.
+ */
+export declare const CF_EXT_URI = "{78C0D931-6437-407d-A8EE-F0AAD7539E65}";
+export declare const DATABAR_LINK_EXT_URI = "{B025F937-C7B1-47D3-B67F-A62EFF666E3E}";
+export declare const DATA_VALIDATION_EXT_URI = "{CCE6A557-97BC-4b89-ADB6-D9C93CAAB3DF}";
+export declare const SLICER_LIST_EXT_URI = "{A8765BA9-456A-4dab-B4F3-ACF838C121DE}";
+export declare const SLICER_CACHES_EXT_URI = "{BBE1A952-AA13-448e-AADC-164F8A28A991}";

package/dist/io/xlsx/namespaces.js

@@ -0,0 +1,55 @@
+/**
+ * Canonical SpreadsheetML namespace URIs and well-known extension GUIDs.
+ *
+ * These are wire-format constants: Excel keys its parsing off the exact URI or
+ * GUID, so a producer must reproduce each one byte-for-byte. Centralizing them
+ * keeps the writer and reader from drifting apart and retires the
+ * `NS_MAIN`/`MAIN_NS`/`main` naming fork that had grown across the io modules.
+ *
+ * The package-level URIs (`.rels`, content types, the relationship vocabulary) describe the
+ * container rather than the spreadsheet inside it, and live in `../opc/namespaces.ts`.
+ */
+/**
+ * SpreadsheetML main namespace — the default `xmlns` of the workbook,
+ * worksheet, styles, sharedStrings, comments, table and pivot parts.
+ */
+export const SPREADSHEETML_NS = 'http://schemas.openxmlformats.org/spreadsheetml/2006/main';
+/**
+ * Markup-compatibility namespace (`mc:`), whose `mc:Ignorable` attribute lists the prefixes a
+ * consumer that does not know them may skip rather than reject the part over.
+ */
+export const MARKUP_COMPATIBILITY_NS = 'http://schemas.openxmlformats.org/markup-compatibility/2006';
+/**
+ * The 2014 revision namespace (`xr:`), which scopes the `xr:uid` Excel stamps on a comment. Declared
+ * `mc:Ignorable` wherever it appears, so a consumer that ignores it still reads the part.
+ */
+export const REVISION_NS = 'http://schemas.microsoft.com/office/spreadsheetml/2014/revision';
+/**
+ * The 2018 threaded-comments namespace, shared by both parts of the feature — a sheet's
+ * `threadedComment{n}.xml` and the workbook's `person.xml`. Note the plural `threadedcomments`, all
+ * lower-case: Excel matches the URI exactly and reads neither part under any other spelling.
+ */
+export const THREADED_COMMENTS_NS = 'http://schemas.microsoft.com/office/spreadsheetml/2018/threadedcomments';
+/** DrawingML shared graphics namespace (`a:`). */
+export const DRAWINGML_NS = 'http://schemas.openxmlformats.org/drawingml/2006/main';
+/** Spreadsheet-drawing anchor namespace (`xdr:`) used by the worksheet drawing part. */
+export const XDR_NS = 'http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing';
+/**
+ * The 2009 Microsoft extension namespace. `x14` scopes the feature elements
+ * Excel tucks inside `<ext>` blocks (conditional formatting, data validation,
+ * slicers); it is declared inline on those elements exactly as Excel writes
+ * them, so a worksheet root never needs an extra namespace declaration.
+ */
+export const X14_NS = 'http://schemas.microsoft.com/office/spreadsheetml/2009/9/main';
+/** Scopes the `<xm:sqref>`/`<xm:f>` references the x14 feature elements carry. */
+export const XM_NS = 'http://schemas.microsoft.com/office/excel/2006/main';
+/**
+ * Well-known `<ext uri=…>` GUIDs. Each `<ext>` block is opaque to a consumer
+ * that does not recognize its GUID, so a producer must emit these exact values
+ * for Excel to rediscover the feature.
+ */
+export const CF_EXT_URI = '{78C0D931-6437-407d-A8EE-F0AAD7539E65}';
+export const DATABAR_LINK_EXT_URI = '{B025F937-C7B1-47D3-B67F-A62EFF666E3E}';
+export const DATA_VALIDATION_EXT_URI = '{CCE6A557-97BC-4b89-ADB6-D9C93CAAB3DF}';
+export const SLICER_LIST_EXT_URI = '{A8765BA9-456A-4dab-B4F3-ACF838C121DE}';
+export const SLICER_CACHES_EXT_URI = '{BBE1A952-AA13-448e-AADC-164F8A28A991}';

package/dist/io/xlsx/package-plan.d.ts

@@ -0,0 +1,103 @@
+import type { CommentThread } from '../../core/comment-thread.ts';
+import type { PivotTable } from '../../core/pivot-table.ts';
+import type { Table } from '../../core/table.ts';
+import type { Workbook } from '../../core/workbook.ts';
+import type { Worksheet } from '../../core/worksheet.ts';
+import type { CommentCell } from './comments.ts';
+import type { DrawingImage } from './images.ts';
+export declare class SheetRelIds {
+    #private;
+    /** The next relationship id (`rId1`, `rId2`, …), advancing the counter. */
+    next(): string;
+}
+export interface PivotPlan {
+    readonly number: number;
+    readonly cacheId: string;
+    readonly table: PivotTable;
+    readonly sheetRelId: string;
+    workbookRelId: string;
+}
+export interface CommentPlan {
+    readonly number: number;
+    readonly comments: readonly CommentCell[];
+    readonly vmlRelId: string;
+    readonly commentsRelId: string;
+}
+export interface ThreadedCommentPlan {
+    readonly number: number;
+    readonly threads: readonly CommentThread[];
+    readonly relId: string;
+}
+export interface PrinterSettingsPlan {
+    readonly number: number;
+    readonly data: Uint8Array;
+    readonly relId: string;
+}
+export interface TablePlan {
+    readonly table: Table;
+    readonly number: number;
+    readonly relId: string;
+}
+export interface BackgroundPlan {
+    readonly relId: string;
+    readonly mediaNumber: number;
+    readonly extension: string;
+}
+export interface PreservedPartPlan {
+    readonly path: string;
+    readonly bytes: Uint8Array;
+    readonly contentType: string;
+    readonly relsPath: string | null;
+    readonly relsXml: string | null;
+}
+export interface ResolvedPreservedReference {
+    readonly element: 'drawing' | 'legacyDrawingHF' | undefined;
+    readonly relType: string;
+    readonly entryPath: string;
+}
+export interface PreservedReferencePlan extends ResolvedPreservedReference {
+    readonly relId: string;
+}
+export interface PreservedWorkbookReferencePlan {
+    readonly relType: string;
+    readonly entryPath: string;
+    readonly pivotCacheId: string | undefined;
+    readonly externalReferenceIndex: number | undefined;
+}
+export interface PreservedRootReferencePlan {
+    readonly relType: string;
+    readonly entryPath: string;
+}
+export interface PreservedPlan {
+    readonly perSheet: readonly (readonly ResolvedPreservedReference[])[];
+    readonly workbook: readonly PreservedWorkbookReferencePlan[];
+    readonly root: readonly PreservedRootReferencePlan[];
+    readonly parts: readonly PreservedPartPlan[];
+    /**
+     * Whether a source theme rides in {@link parts} at {@link THEME_PART_PATH}. The theme relationship
+     * and content-type override are emitted unconditionally either way; this only tells the writer
+     * whether to *also* generate its default theme body, which would otherwise clobber the preserved one.
+     */
+    readonly themeEmitted: boolean;
+}
+export interface DrawingPlan {
+    readonly number: number;
+    readonly relId: string;
+    readonly images: readonly ImagePlan[];
+}
+export interface ImagePlan extends DrawingImage {
+    readonly mediaNumber: number;
+    readonly extension: string;
+}
+export interface MediaPart {
+    readonly number: number;
+    readonly extension: string;
+    readonly data: Uint8Array;
+}
+export interface MediaPlan {
+    readonly parts: readonly MediaPart[];
+    readonly numberById: ReadonlyMap<number, number>;
+    readonly extensions: readonly string[];
+}
+export declare function planMedia(workbook: Workbook, sheets: readonly Worksheet[]): MediaPlan;
+export declare function planPreservedParts(workbook: Workbook, generatedDrawingCount: number, generatedMediaCount: number): PreservedPlan;

package/dist/io/xlsx/package-plan.js

@@ -0,0 +1,168 @@
+// The plan layer of the writer: pure graph resolution that turns a Workbook model into the numbered,
+// cross-referenced set of parts an `.xlsx` package needs — media, preserved (verbatim-carried) parts,
+// and the sheet-/workbook-local relationship ids that wire them — before any XML is serialised.
+import { AuthoringError } from "../../errors.js";
+import { extensionOf, relativePartPath, relsPathFor, THEME_PART_PATH } from "../opc/part-paths.js";
+import { preservedRelsXml } from "../opc/rels.js";
+// A sheet's relationship-id allocator: hands out `rId1`, `rId2`, … in the one canonical order the
+// package wires a sheet's parts (tables, drawing, comments, threaded comments, printer settings, external
+// hyperlinks, background, preserved references, pivot tables). Every sheet-local id is drawn from here in
+// sequence, so no plan step re-derives its starting offset by summing the counts of the steps before
+// it — the arithmetic that, open-coded once per step with subtly different prefixes, could silently
+// hand two parts the same id and corrupt the package. Monotonic by construction, so collisions cannot
+// arise however the steps grow. One fresh allocator per sheet; the ids it yields are sheet-local.
+export class SheetRelIds {
+    #next = 1;
+    /** The next relationship id (`rId1`, `rId2`, …), advancing the counter. */
+    next() {
+        return `rId${this.#next++}`;
+    }
+}
+// Gather the workbook images actually referenced by some sheet — either anchored in a drawing or set
+// as a sheet background (an unreferenced image is not written) — number them in first-use order, and
+// record the extensions in play. A sheet referencing an id with no registered image is a programming
+// error the writer surfaces rather than emitting a dangling relationship.
+export function planMedia(workbook, sheets) {
+    const usedIds = [];
+    const seen = new Set();
+    const use = (id) => {
+        if (!seen.has(id)) {
+            seen.add(id);
+            usedIds.push(id);
+        }
+    };
+    for (const sheet of sheets) {
+        for (const image of sheet.images)
+            use(image.imageId);
+        if (sheet.backgroundImageId !== undefined)
+            use(sheet.backgroundImageId);
+    }
+    const parts = [];
+    const numberById = new Map();
+    const extensions = new Set();
+    usedIds.forEach((id, i) => {
+        const image = workbook.getImage(id);
+        if (image === undefined) {
+            throw new AuthoringError(`a worksheet anchors image id ${id}, which is not registered on the workbook`);
+        }
+        const number = i + 1;
+        parts.push({ number, extension: image.extension, data: image.data });
+        numberById.set(id, number);
+        extensions.add(image.extension);
+    });
+    return { parts, numberById, extensions: [...extensions] };
+}
+// Resolve every sheet's verbatim-preserved worksheet references (a vector-shape drawing, a
+// header/footer image) into the parts to emit and the per-sheet reference data that wires them. Each
+// reference's captured part closure is re-numbered onto collision-proof `preservedP{n}` paths — so
+// preserved content never clobbers a generated drawing/VML/media part — with the closure's internal
+// relationships rewritten to the new sibling paths. Part numbering is the only cross-sheet concern
+// here; each reference's sheet-local relationship id is assigned by the caller from the sheet's
+// {@link SheetRelIds} allocator, so this function stays free of the sheet-local id arithmetic.
+export function planPreservedParts(workbook, generatedDrawingCount, generatedMediaCount) {
+    const sheets = workbook.worksheets;
+    // The writer generates drawings, VML, and media of its own, so a preserved part of one of those
+    // kinds is re-numbered past the generated ones (a preserved drawing never clobbers an anchored
+    // drawing, a preserved VML never clobbers a comment's VML). Comment VML is numbered by sheet index,
+    // so `sheets.length` bounds it. Every other kind (pivot tables, caches, slicers, charts) the writer
+    // never generates, so those keep their original path — see {@link preservedPartPath}.
+    const numbering = {
+        drawing: generatedDrawingCount,
+        vml: sheets.length,
+        media: generatedMediaCount,
+    };
+    // One package-wide remap and one emitted-parts map: a part reached through more than one reference
+    // (a pivot cache reached both from its pivot table and from the workbook) is numbered once and
+    // emitted once, so overlapping closures collapse instead of duplicating parts.
+    const remap = new Map();
+    // A preserved theme rides the same closure machinery as every other verbatim part — it can carry
+    // relationships of its own (a picture used as a themed fill) that need the same renumbering and
+    // rewiring. Its entry is pinned to the fixed theme path rather than left to {@link preservedPartPath},
+    // because the workbook's theme relationship and the content-type override name that path
+    // unconditionally; a source package that called its part `theme2.xml` would otherwise land it
+    // somewhere neither points.
+    const theme = workbook.themePart;
+    if (theme !== undefined)
+        remap.set(theme.entryPath, THEME_PART_PATH);
+    const allReferences = [
+        ...sheets.flatMap((sheet) => sheet.preservedReferences),
+        ...workbook.preservedReferences,
+        ...workbook.preservedRootReferences,
+        ...(theme === undefined ? [] : [theme]),
+    ];
+    for (const reference of allReferences) {
+        for (const part of reference.parts) {
+            if (!remap.has(part.path))
+                remap.set(part.path, preservedPartPath(part.path, numbering));
+        }
+    }
+    const emitted = new Map();
+    for (const reference of allReferences) {
+        for (const part of reference.parts) {
+            const newPath = remap.get(part.path);
+            if (emitted.has(newPath))
+                continue;
+            const rels = part.rels.flatMap((rel) => {
+                // An external relationship (a linked workbook) is emitted verbatim — its target is outside the
+                // package, so it is neither in the remap nor expressed relative to the new path.
+                if (rel.external) {
+                    return [{ id: rel.id, type: rel.type, target: rel.targetPath, external: true }];
+                }
+                const target = remap.get(rel.targetPath);
+                return target === undefined
+                    ? []
+                    : [{ id: rel.id, type: rel.type, target: relativePartPath(newPath, target) }];
+            });
+            // The one preserved part whose *bytes* can change: a theme the caller authored over is
+            // regenerated from the source part (see `Workbook.authoredThemeXml`) rather than carried
+            // verbatim, so the format scheme, the unauthored slots' encoding, and the relationships below
+            // all still ride through — only the authored elements differ.
+            const authoredTheme = newPath === THEME_PART_PATH ? workbook.authoredThemeXml() : undefined;
+            emitted.set(newPath, {
+                path: newPath,
+                bytes: authoredTheme === undefined ? part.bytes : new TextEncoder().encode(authoredTheme),
+                contentType: part.contentType,
+                relsPath: rels.length === 0 ? null : relsPathFor(newPath),
+                relsXml: rels.length === 0 ? null : preservedRelsXml(rels),
+            });
+        }
+    }
+    const perSheet = sheets.map((sheet) => sheet.preservedReferences.map((reference) => ({
+        element: reference.element,
+        relType: reference.relType,
+        entryPath: remap.get(reference.entryPath),
+    })));
+    const workbookRefs = workbook.preservedReferences.map((reference) => ({
+        relType: reference.relType,
+        entryPath: remap.get(reference.entryPath),
+        pivotCacheId: reference.pivotCacheId,
+        externalReferenceIndex: reference.externalReferenceIndex,
+    }));
+    const rootRefs = workbook.preservedRootReferences.map((reference) => ({
+        relType: reference.relType,
+        entryPath: remap.get(reference.entryPath),
+    }));
+    return {
+        perSheet,
+        workbook: workbookRefs,
+        root: rootRefs,
+        parts: [...emitted.values()],
+        themeEmitted: theme !== undefined,
+    };
+}
+// The path a preserved part is emitted at. A kind the writer generates of its own — a drawing, a VML,
+// a media image — is re-numbered past the generated parts of that kind (see {@link planPreservedParts})
+// so it never clobbers one. Every other kind (a pivot table, a pivot/slicer cache, a slicer, a chart)
+// the writer never generates, so it keeps its original path — leaving the package's standard part
+// names intact and letting overlapping closures agree on a single path for a shared part.
+function preservedPartPath(originalPath, numbering) {
+    const ext = extensionOf(originalPath);
+    if (ext.toLowerCase() === 'vml')
+        return `xl/drawings/vmlDrawing${++numbering.vml}.vml`;
+    if (originalPath.startsWith('xl/media/'))
+        return `xl/media/image${++numbering.media}.${ext}`;
+    if (originalPath.startsWith('xl/drawings/') && ext.toLowerCase() === 'xml') {
+        return `xl/drawings/drawing${++numbering.drawing}.xml`;
+    }
+    return originalPath;
+}

package/dist/io/xlsx/pivot-read.d.ts

@@ -0,0 +1,5 @@
+import { type ParsedPivotTable } from '../../core/pivot-table.ts';
+/** Reconstruct a pivot's semantic model from its two definition parts. The records part is not
+ * consulted: the cache's field catalogue and the table's field roles fully describe the pivot's
+ * shape, and the aggregated values are Excel's to compute on refresh. */
+export declare function parsePivotTable(tableXml: string, cacheXml: string): ParsedPivotTable;