@shbernal/ts-xlsx 3.0.0 → 3.2.0

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

@@ -1,12 +1,39 @@
-import { AuthoringError } from '../../errors.js';
+import { INTERNAL } from '../../core/internal.js';
+import { AuthoringError, InternalError, quoted } from '../../errors.js';
 import { extensionOf, relativePartPath, relsPathFor, THEME_PART_PATH } from '../opc/part-paths.js';
 import { relsPartXml } from '../opc/rels.js';
-import { drawingPart, mediaPart, vmlDrawingPart } from './part-names.js';
+import { mergePictures } from './images.js';
+import { drawingPart, mediaPart, pivotCacheDefinitionPart, pivotCacheRecordsPart, pivotTablePart, vmlDrawingPart, } from './part-names.js';
+import { splicePreservedPart } from './preserved-splices.js';
 import { applyThemeOverrides } from './theme-xml.js';
-export class SheetRelIds {
+export class RelationshipLedger {
+    #owner;
+    #taken;
+    #relationships = [];
     #next = 1;
-    next() {
-        return `rId${this.#next++}`;
+    constructor(owner, taken = new Set()) {
+        this.#owner = owner;
+        this.#taken = taken;
+    }
+    add(type, partPath) {
+        return this.#record({ type, target: relativePartPath(this.#owner, partPath) });
+    }
+    addExternal(type, url) {
+        return this.#record({ type, target: url, external: true });
+    }
+    addInDocument(type, location) {
+        return this.#record({ type, target: location });
+    }
+    get relationships() {
+        return this.#relationships;
+    }
+    #record(relationship) {
+        while (this.#taken.has(`rId${this.#next}`))
+            this.#next += 1;
+        const id = `rId${this.#next}`;
+        this.#next += 1;
+        this.#relationships.push({ id, ...relationship });
+        return id;
     }
 }
 export function planMedia(workbook, sheets) {
@@ -32,7 +59,7 @@ export function planMedia(workbook, sheets) {
         const image = workbook.getImage(id);
         if (image === undefined) {
             const reference = role === 'anchor' ? `anchors image id ${id}` : `sets background image id ${id}`;
-            throw new AuthoringError(`sheet "${sheetName}" ${reference}, which is not registered on the workbook`);
+            throw new AuthoringError(`sheet ${quoted(sheetName)} ${reference}, which is not registered on the workbook`);
         }
         const number = i + 1;
         parts.push({ number, extension: image.extension, data: image.data });
@@ -51,12 +78,15 @@ export function planMedia(workbook, sheets) {
         },
     };
 }
-export function planPreservedParts(workbook, generatedDrawingCount, generatedMediaCount) {
+export function planPreservedParts(workbook, generatedDrawingCount, generatedMediaCount, generatedPivotCount, pictures) {
     const sheets = workbook.worksheets;
     const numbering = {
         drawing: generatedDrawingCount,
         vml: sheets.length,
         media: generatedMediaCount,
+        pivotTable: generatedPivotCount,
+        pivotCacheDefinition: generatedPivotCount,
+        pivotCacheRecords: generatedPivotCount,
     };
     const remap = new Map();
     const theme = workbook.themePart;
@@ -75,9 +105,10 @@ export function planPreservedParts(workbook, generatedDrawingCount, generatedMed
         }
     }
     const emitted = new Map();
+    const splices = workbook[INTERNAL].splices();
     for (const reference of allReferences) {
         for (const part of reference.parts) {
-            const newPath = remap.get(part.path);
+            const newPath = resolveRemapped(remap, part.path);
             if (emitted.has(newPath))
                 continue;
             const rels = part.rels.flatMap((rel) => {
@@ -90,31 +121,40 @@ export function planPreservedParts(workbook, generatedDrawingCount, generatedMed
                     : [{ id: rel.id, type: rel.type, target: relativePartPath(newPath, target) }];
             });
             const overrides = newPath === THEME_PART_PATH ? workbook.themeOverrides : undefined;
+            let bytes = overrides === undefined
+                ? splicePreservedPart(part.bytes, part.contentType, splices)
+                : new TextEncoder().encode(applyThemeOverrides(new TextDecoder().decode(part.bytes), overrides));
+            let relationships = rels;
+            const joining = pictures.get(part.path);
+            if (joining !== undefined) {
+                const ledger = new RelationshipLedger(newPath, new Set(rels.map((rel) => rel.id)));
+                const images = joining(ledger);
+                bytes = new TextEncoder().encode(mergePictures(new TextDecoder().decode(bytes), images));
+                relationships = [...rels, ...ledger.relationships];
+            }
             emitted.set(newPath, {
                 path: newPath,
-                bytes: overrides === undefined
-                    ? part.bytes
-                    : new TextEncoder().encode(applyThemeOverrides(new TextDecoder().decode(part.bytes), overrides)),
+                bytes,
                 contentType: part.contentType,
-                relsPath: rels.length === 0 ? null : relsPathFor(newPath),
-                relsXml: rels.length === 0 ? null : relsPartXml(rels),
+                relsPath: relationships.length === 0 ? null : relsPathFor(newPath),
+                relsXml: relationships.length === 0 ? null : relsPartXml(relationships),
             });
         }
     }
     const perSheet = sheets.map((sheet) => sheet.preservedReferences.map((reference) => ({
         element: reference.element,
         relType: reference.relType,
-        entryPath: remap.get(reference.entryPath),
+        entryPath: resolveRemapped(remap, reference.entryPath),
     })));
     const workbookRefs = workbook.preservedReferences.map((reference) => ({
         relType: reference.relType,
-        entryPath: remap.get(reference.entryPath),
+        entryPath: resolveRemapped(remap, reference.entryPath),
         pivotCacheId: reference.pivotCacheId,
         externalReferenceIndex: reference.externalReferenceIndex,
     }));
     const rootRefs = workbook.preservedRootReferences.map((reference) => ({
         relType: reference.relType,
-        entryPath: remap.get(reference.entryPath),
+        entryPath: resolveRemapped(remap, reference.entryPath),
     }));
     return {
         perSheet,
@@ -124,14 +164,39 @@ export function planPreservedParts(workbook, generatedDrawingCount, generatedMed
         themeEmitted: theme !== undefined,
     };
 }
+function resolveRemapped(remap, path) {
+    const resolved = remap.get(path);
+    if (resolved === undefined) {
+        throw new InternalError(`preserved part ${quoted(path)} was never assigned a new path`);
+    }
+    return resolved;
+}
 function preservedPartPath(originalPath, numbering) {
     const ext = extensionOf(originalPath);
-    if (ext.toLowerCase() === 'vml')
+    if (ext === 'vml')
         return vmlDrawingPart(++numbering.vml);
     if (originalPath.startsWith('xl/media/'))
         return mediaPart(++numbering.media, ext);
-    if (originalPath.startsWith('xl/drawings/') && ext.toLowerCase() === 'xml') {
+    if (originalPath.startsWith('xl/drawings/') && ext === 'xml') {
         return drawingPart(++numbering.drawing);
     }
+    if (isNumberedPart(originalPath, PIVOT_TABLE_PREFIX)) {
+        return pivotTablePart(++numbering.pivotTable);
+    }
+    if (isNumberedPart(originalPath, PIVOT_CACHE_DEFINITION_PREFIX)) {
+        return pivotCacheDefinitionPart(++numbering.pivotCacheDefinition);
+    }
+    if (isNumberedPart(originalPath, PIVOT_CACHE_RECORDS_PREFIX)) {
+        return pivotCacheRecordsPart(++numbering.pivotCacheRecords);
+    }
     return originalPath;
 }
+const PIVOT_TABLE_PREFIX = numberedPartPrefix(pivotTablePart);
+const PIVOT_CACHE_DEFINITION_PREFIX = numberedPartPrefix(pivotCacheDefinitionPart);
+const PIVOT_CACHE_RECORDS_PREFIX = numberedPartPrefix(pivotCacheRecordsPart);
+function numberedPartPrefix(part) {
+    return part(1).slice(0, -'1.xml'.length);
+}
+function isNumberedPart(path, prefix) {
+    return path.startsWith(prefix) && /^\d+\.xml$/.test(path.slice(prefix.length));
+}

package/dist/io/xlsx/part-names.d.ts

@@ -5,6 +5,12 @@ export declare const SHARED_STRINGS_PART = "xl/sharedStrings.xml";
 /** Singular and unnumbered, unlike the per-sheet thread parts: one identity registry serves the
  * whole workbook's threaded comments. */
 export declare const PERSONS_PART = "xl/persons/person.xml";
+/** The metadata a `<c cm>` and `<c vm>` index: what marks a formula a dynamic array, and what names
+ * the error behind a `#VALUE!`. */
+export declare const METADATA_PART = "xl/metadata.xml";
+/** The rich values a value-metadata block names, and the structures they are read against. */
+export declare const RICH_VALUES_PART = "xl/richData/rdrichvalue.xml";
+export declare const RICH_VALUE_STRUCTURES_PART = "xl/richData/rdrichvaluestructure.xml";
 export declare const CORE_PROPS_PART = "docProps/core.xml";
 export declare const APP_PROPS_PART = "docProps/app.xml";
 /** `xl/worksheets/sheet{n}.xml`, numbered by the sheet's position in the workbook (1-based). */
@@ -31,11 +37,3 @@ export declare function pivotTablePart(number: number): string;
 export declare function pivotCacheDefinitionPart(number: number): string;
 /** `xl/pivotCache/pivotCacheRecords{n}.xml`: the cached rows the definition points at. */
 export declare function pivotCacheRecordsPart(number: number): string;
-/**
- * A part named as a Target of a relationship carried by a *worksheet*. Every worksheet part lives in
- * `xl/worksheets/`, so one sheet's view of a target is every sheet's, and the sheet number the
- * arithmetic runs against does not matter.
- */
-export declare function targetFromWorksheet(partPath: string): string;
-/** A part named as a Target of a relationship carried by the workbook part. */
-export declare function targetFromWorkbook(partPath: string): string;

package/dist/io/xlsx/part-names.js

@@ -1,8 +1,10 @@
-import { relativePartPath } from '../opc/part-paths.js';
 export const WORKBOOK_PART = 'xl/workbook.xml';
 export const STYLES_PART = 'xl/styles.xml';
 export const SHARED_STRINGS_PART = 'xl/sharedStrings.xml';
 export const PERSONS_PART = 'xl/persons/person.xml';
+export const METADATA_PART = 'xl/metadata.xml';
+export const RICH_VALUES_PART = 'xl/richData/rdrichvalue.xml';
+export const RICH_VALUE_STRUCTURES_PART = 'xl/richData/rdrichvaluestructure.xml';
 export const CORE_PROPS_PART = 'docProps/core.xml';
 export const APP_PROPS_PART = 'docProps/app.xml';
 export function worksheetPart(number) {
@@ -38,9 +40,3 @@ export function pivotCacheDefinitionPart(number) {
 export function pivotCacheRecordsPart(number) {
     return `xl/pivotCache/pivotCacheRecords${number}.xml`;
 }
-export function targetFromWorksheet(partPath) {
-    return relativePartPath(worksheetPart(1), partPath);
-}
-export function targetFromWorkbook(partPath) {
-    return relativePartPath(WORKBOOK_PART, partPath);
-}

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

@@ -1,9 +1,9 @@
 import type { PivotTable } from '../../core/pivot-table.ts';
-/** The `pivotCacheDefinition` part: the source reference and the field catalogue. `r:id="rId1"`
- * names the cache-records part through this cache's own rels part. `refreshOnLoad="1"` tells Excel to
- * rebuild the pivot body from the cache on open, so the layout stays correct without us computing it
- * to the pixel. `recordCount` is the number of source data rows. */
-export declare function pivotCacheDefinitionXml(table: PivotTable): string;
+/** The `pivotCacheDefinition` part: the source reference and the field catalogue. `recordsRelId` is
+ * the id this cache's own rels part gives the cache-records part, which `r:id` cites.
+ * `refreshOnLoad="1"` tells Excel to rebuild the pivot body from the cache on open, so the layout stays
+ * correct without us computing it to the pixel. `recordCount` is the number of source data rows. */
+export declare function pivotCacheDefinitionXml(table: PivotTable, recordsRelId: string): string;
 /** The `pivotCacheRecords` part: one `<r>` per source data row, each cell either an index into an
  * axis field's shared-items catalogue (`<x>`) or an inline value (`<n>`/`<s>`/`<m>`). */
 export declare function pivotCacheRecordsXml(table: PivotTable): string;

package/dist/io/xlsx/pivot.js

@@ -1,5 +1,5 @@
 import { encodeAddress } from '../../core/address.js';
-import { escapeAttr, XML_DECLARATION } from '../../xml/xml.js';
+import { escapeAttr, numberText, XML_DECLARATION } from '../../xml/xml.js';
 import { RELATIONSHIPS_NS } from '../opc/namespaces.js';
 import { SPREADSHEETML_NS } from './namespaces.js';
 const METRIC_CAPTIONS = {
@@ -15,29 +15,19 @@ const METRIC_CAPTIONS = {
     var: 'Var',
     varp: 'Varp',
 };
-export function pivotCacheDefinitionXml(table) {
+export function pivotCacheDefinitionXml(table, recordsRelId) {
     const fields = table.cacheFields
         .map((field) => {
         const shared = field.sharedItems;
-        if (shared !== null) {
-            const items = shared.map(sharedItemXml).join('');
-            const blank = field.containsBlank ? ' containsBlank="1"' : '';
-            return (`<cacheField name="${escapeAttr(field.name)}" numFmtId="0">` +
-                `<sharedItems${blank} count="${shared.length}">${items}</sharedItems>` +
-                `</cacheField>`);
-        }
-        const blank = field.containsBlank ? ' containsBlank="1"' : '';
-        const numeric = field.numeric;
-        const descriptor = numeric === null
-            ? `<sharedItems${blank}/>`
-            : `<sharedItems containsSemiMixedTypes="0" containsString="0" containsNumber="1" ` +
-                `containsInteger="${numeric.allInteger ? 1 : 0}"${blank} ` +
-                `minValue="${numeric.min}" maxValue="${numeric.max}"/>`;
+        const kinds = sharedItemsKinds(field);
+        const descriptor = shared === null
+            ? `<sharedItems${kinds}/>`
+            : `<sharedItems${kinds} count="${shared.length}">${shared.map(sharedItemXml).join('')}</sharedItems>`;
         return `<cacheField name="${escapeAttr(field.name)}" numFmtId="0">${descriptor}</cacheField>`;
     })
         .join('');
     return (XML_DECLARATION +
-        `<pivotCacheDefinition xmlns="${SPREADSHEETML_NS}" xmlns:r="${RELATIONSHIPS_NS}" r:id="rId1" refreshOnLoad="1" ` +
+        `<pivotCacheDefinition xmlns="${SPREADSHEETML_NS}" xmlns:r="${RELATIONSHIPS_NS}" r:id="${escapeAttr(recordsRelId)}" refreshOnLoad="1" ` +
         `refreshedBy="ts-xlsx" createdVersion="8" refreshedVersion="8" minRefreshableVersion="3" ` +
         `recordCount="${table.records.length}">` +
         `<cacheSource type="worksheet">` +
@@ -56,22 +46,21 @@ export function pivotCacheRecordsXml(table) {
         `</pivotCacheRecords>`);
 }
 export function pivotTableXml(table, name, cacheId) {
-    const rowField = table.rowFields[0];
-    const columnField = table.columnFields[0];
+    const rowField = table.rowFields[0] ?? 0;
+    const columnField = table.columnFields[0] ?? 0;
     const rowGroups = table.cacheFields[rowField]?.sharedItems?.length ?? 1;
     const columnGroups = table.cacheFields[columnField]?.sharedItems?.length ?? 1;
     const location = `A1:${encodeAddress(2 + columnGroups, 3 + rowGroups)}`;
     const pivotFields = table.cacheFields
         .map((field, index) => {
+        const dataField = index === table.valueField ? ' dataField="1"' : '';
         if (table.rowFields.includes(index) || table.columnFields.includes(index)) {
             const axis = table.rowFields.includes(index) ? 'axisRow' : 'axisCol';
             const items = field.sharedItems ?? [];
             const entries = `${items.map((_item, i) => `<item x="${i}"/>`).join('')}<item t="default"/>`;
-            return `<pivotField axis="${axis}" showAll="0"><items count="${items.length + 1}">${entries}</items></pivotField>`;
+            return `<pivotField axis="${axis}"${dataField} showAll="0"><items count="${items.length + 1}">${entries}</items></pivotField>`;
         }
-        if (index === table.valueField)
-            return '<pivotField dataField="1" showAll="0"/>';
-        return '<pivotField showAll="0"/>';
+        return `<pivotField${dataField} showAll="0"/>`;
     })
         .join('');
     const rowFields = table.rowFields.map((index) => `<field x="${index}"/>`).join('');
@@ -102,12 +91,25 @@ function dataFieldXml(table) {
     return (`<dataField name="${escapeAttr(caption)}" fld="${table.valueField}"${subtotal} ` +
         `baseField="0" baseItem="0"/>`);
 }
+function sharedItemsKinds(field) {
+    const { containsString, containsBlank, numeric } = field;
+    const hasNumber = numeric !== null;
+    return ((!containsString && !containsBlank && hasNumber ? ' containsSemiMixedTypes="0"' : '') +
+        (containsString ? '' : ' containsString="0"') +
+        (containsBlank ? ' containsBlank="1"' : '') +
+        (containsString && hasNumber ? ' containsMixedTypes="1"' : '') +
+        (numeric === null
+            ? ''
+            : ' containsNumber="1"' +
+                (numeric.allInteger ? ' containsInteger="1"' : '') +
+                ` minValue="${numberText(numeric.min)}" maxValue="${numberText(numeric.max)}"`));
+}
 function sharedItemXml(item) {
     switch (item.kind) {
         case 'string':
             return `<s v="${escapeAttr(item.value)}"/>`;
         case 'number':
-            return `<n v="${item.value}"/>`;
+            return `<n v="${numberText(item.value)}"/>`;
         case 'blank':
             return '<m/>';
     }

package/dist/io/xlsx/preserved-splices.d.ts

@@ -0,0 +1,6 @@
+import { type SheetSplice } from '../../core/formula-references.ts';
+/**
+ * A preserved part's bytes with the references it spells moved through `splices`, in order, or the
+ * same bytes when the part is of a kind that spells none or nothing in it moved.
+ */
+export declare function splicePreservedPart(bytes: Uint8Array, contentType: string, splices: readonly SheetSplice[]): Uint8Array;

package/dist/io/xlsx/preserved-splices.js

@@ -0,0 +1,74 @@
+import { spliceFormula } from '../../core/formula-references.js';
+import { splicePivotSource } from '../../core/pivot-table.js';
+import { XmlParseError } from '../../xml/errors.js';
+import { elementRange, elementRanges, openElements } from '../../xml/xml-read.js';
+import { decodeEntities } from '../../xml/xml-scan.js';
+import { escapeText, startTag } from '../../xml/xml.js';
+import { relAttr } from '../opc/namespaces.js';
+const chartReferences = (xml, splices) => {
+    const edits = [];
+    for (const range of elementRanges(xml, 'f')) {
+        const content = xml.slice(range.contentStart, range.contentEnd);
+        if (content.includes('<'))
+            continue;
+        const formula = decodeEntities(content);
+        const moved = splices.reduce((text, edit) => spliceFormula(text, undefined, edit), formula);
+        if (moved !== formula) {
+            edits.push({ start: range.contentStart, end: range.contentEnd, text: escapeText(moved) });
+        }
+    }
+    return edits;
+};
+const pivotCacheSource = (xml, splices) => {
+    for (const source of openElements(xml, 'worksheetSource')) {
+        if (relAttr(source.scope, source.attrs, 'id') !== undefined)
+            return [];
+        break;
+    }
+    const range = elementRange(xml, ['cacheSource', 'worksheetSource']);
+    const { sheet, ref } = range?.attrs ?? {};
+    if (range === undefined || sheet === undefined || ref === undefined)
+        return [];
+    const moved = splices.reduce((text, edit) => splicePivotSource(sheet, text, edit), ref);
+    if (moved === ref)
+        return [];
+    return [
+        {
+            start: range.start,
+            end: range.end,
+            text: startTag(range.name, { ...range.attrs, ref: moved }, true),
+        },
+    ];
+};
+const REWRITERS = new Map([
+    ['application/vnd.openxmlformats-officedocument.drawingml.chart+xml', chartReferences],
+    ['application/vnd.ms-office.chartex+xml', chartReferences],
+    [
+        'application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheDefinition+xml',
+        pivotCacheSource,
+    ],
+].map(([type, rewrite]) => [type.toLowerCase(), rewrite]));
+export function splicePreservedPart(bytes, contentType, splices) {
+    if (splices.length === 0)
+        return bytes;
+    const rewrite = REWRITERS.get(contentType.toLowerCase());
+    if (rewrite === undefined)
+        return bytes;
+    const source = new TextDecoder().decode(bytes);
+    let edits;
+    try {
+        edits = rewrite(source, splices);
+    }
+    catch (error) {
+        if (error instanceof XmlParseError)
+            return bytes;
+        throw error;
+    }
+    if (edits.length === 0)
+        return bytes;
+    let xml = source;
+    for (const edit of edits.toSorted((a, b) => b.start - a.start)) {
+        xml = xml.slice(0, edit.start) + edit.text + xml.slice(edit.end);
+    }
+    return new TextEncoder().encode(xml);
+}

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

@@ -0,0 +1,29 @@
+import type { Worksheet } from '../../core/worksheet.ts';
+/** One `<comment>` read back from a comments part. */
+export interface ParsedComment {
+    readonly text: string;
+    /**
+     * The thread head id this comment is the legacy fallback for, read off its synthetic `tc={headId}`
+     * author; absent for a user's own note.
+     */
+    readonly threadId?: string;
+}
+/**
+ * Parse a `comments{n}.xml` part into a map of A1 reference → comment. Text runs within one comment are
+ * concatenated; an author-name run is Excel's own convention and is not stripped, so a note reads back
+ * as exactly the text that was written.
+ */
+export declare function parseComments(xml: string): Map<string, ParsedComment>;
+/**
+ * Apply a parsed comments part onto a sheet's cells as notes, addressing each by its A1 reference.
+ *
+ * A thread's legacy fallback is not a note and does not become one: its text is boilerplate wrapping a
+ * copy of the conversation, so surfacing it as `cell.note` hands the caller garbage, and on write it
+ * would be re-emitted as a plain note, destroying the `tc=`/`xr:uid` binding and leaving Excel unable to
+ * see the thread at all.
+ *
+ * Suppressed only for a conversation the reader actually holds: a file whose thread part is missing or
+ * damaged has nothing else left, so there the boilerplate is kept rather than the content lost. Call
+ * after the sheet's threads are restored, since that is what this reads to decide.
+ */
+export declare function applyNotes(sheet: Worksheet, comments: ReadonlyMap<string, ParsedComment>): void;

package/dist/io/xlsx/read-comments.js

@@ -0,0 +1,75 @@
+import { tryDecodeCellRef } from '../../core/address.js';
+import { numInteger } from '../../xml/xml-attrs.js';
+import { parseXml, TextCapture } from '../../xml/xml-read.js';
+import { localName } from '../../xml/xml-scan.js';
+import { RunAccumulator } from './read-rich-runs.js';
+const COMMENT_EMPTY_CLOSES = new Set(['author', 'text']);
+const THREAD_AUTHOR_PREFIX = 'tc=';
+export function parseComments(xml) {
+    const comments = new Map();
+    const authors = [];
+    let currentRef;
+    let currentAuthorId;
+    const author = new TextCapture('author');
+    const bodyRuns = new RunAccumulator({ container: 'text', readRuns: false });
+    let body = '';
+    parseXml(xml, {
+        onOpen(name, attrs, selfClosing) {
+            const local = localName(name);
+            if (local === 'comment') {
+                currentRef = attrs.ref;
+                currentAuthorId = attrs.authorId;
+                body = '';
+            }
+            if (!bodyRuns.open(local, attrs, selfClosing))
+                author.open(local, selfClosing);
+        },
+        onText(text) {
+            bodyRuns.text(text);
+            author.text(text);
+        },
+        onClose(name) {
+            const local = localName(name);
+            const bodyClose = bodyRuns.close(local);
+            if (bodyClose === 'container') {
+                body = bodyRuns.plainText;
+                return;
+            }
+            if (bodyClose === 'claimed')
+                return;
+            const text = author.close(local);
+            if (local === 'author') {
+                authors.push(text ?? '');
+            }
+            else if (local === 'comment' && currentRef !== undefined) {
+                const threadId = threadIdOf(authors[numInteger(currentAuthorId, 0) ?? -1]);
+                comments.set(currentRef, {
+                    text: body,
+                    ...(threadId !== undefined ? { threadId } : {}),
+                });
+                currentRef = undefined;
+                currentAuthorId = undefined;
+            }
+        },
+    }, { closeEmptyElements: COMMENT_EMPTY_CLOSES });
+    return comments;
+}
+function threadIdOf(author) {
+    if (author === undefined || !author.startsWith(THREAD_AUTHOR_PREFIX))
+        return undefined;
+    const id = author.slice(THREAD_AUTHOR_PREFIX.length);
+    return id === '' ? undefined : id;
+}
+export function applyNotes(sheet, comments) {
+    const headIds = new Set(sheet.commentThreads.flatMap((thread) => {
+        const head = thread.comments[0];
+        return head === undefined ? [] : [head.id];
+    }));
+    for (const [ref, comment] of comments) {
+        if (comment.threadId !== undefined && headIds.has(comment.threadId))
+            continue;
+        if (tryDecodeCellRef(ref) === undefined)
+            continue;
+        sheet.getCell(ref).note = comment.text;
+    }
+}

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

@@ -0,0 +1,59 @@
+import type { CommentThread } from '../../core/comment-thread.ts';
+import { Workbook } from '../../core/workbook.ts';
+import type { Worksheet } from '../../core/worksheet.ts';
+import type { CollectingPass } from '../../xml/xml-read.ts';
+import { type PackageAccessors, type PartRelationships } from '../opc/read-opc.ts';
+import { type ParsedComment } from './read-comments.ts';
+/**
+ * What every part reader in one package read shares: the inflated package, the model being built, the
+ * content-type resolver a preserved part's closure is captured through, and the interning map that
+ * makes one workbook image per media part however many places point at it.
+ *
+ * None of the four varies within a read, and threading them positionally is what let `internImage`
+ * end up taking the same three in a different order from both of its callers. What genuinely varies
+ * -- a part's relationships, the sheet being filled -- stays a positional argument, and the sheet's
+ * rels in particular are deliberately *not* in here: they are per sheet, and a stale copy of them
+ * would send every sheet's parts to the first sheet's.
+ */
+export interface PackageReadContext {
+    readonly pkg: PackageAccessors;
+    readonly workbook: Workbook;
+    readonly contentTypeOf: (path: string) => string;
+    readonly imageIdByMediaPath: Map<string, number>;
+}
+export declare function readSheetComments(sheetRels: PartRelationships): Map<string, ParsedComment> | undefined;
+export declare function readWorkbookPersons({ workbook }: PackageReadContext, workbookRels: PartRelationships): void;
+export declare function readWorkbookTheme(context: PackageReadContext, workbookRels: PartRelationships): void;
+export declare function readSheetCommentThreads({ workbook }: PackageReadContext, sheetRels: PartRelationships): CommentThread[];
+export declare function readSheetPrinterSettings(sheetRels: PartRelationships): Uint8Array | undefined;
+export declare function readSheetImages(context: PackageReadContext, sheetRels: PartRelationships, sheet: Worksheet): void;
+export declare function readSheetBackground(context: PackageReadContext, sheetRels: PartRelationships, sheet: Worksheet): void;
+export declare function readSheetPreservedReferences(context: PackageReadContext, sheetRels: PartRelationships, referenceRelIds: WorksheetReferenceRelIds, sheet: Worksheet): void;
+export declare function readWorkbookPreservedReferences(context: PackageReadContext, workbookRels: PartRelationships, registrations: WorkbookRegistrations): void;
+export declare function readRootPreservedReferences(context: PackageReadContext): void;
+/** The two `<pivotCaches>`/`<externalReferences>` registries a preserved reference is wired by,
+ * gathered from the workbook part's own scan rather than from two more of it. */
+export interface WorkbookRegistrations {
+    readonly cacheIdByRelId: ReadonlyMap<string, string>;
+    readonly externalIndexByRelId: ReadonlyMap<string, number>;
+}
+export declare function pivotCacheRegistrationsPass(): CollectingPass<ReadonlyMap<string, string>>;
+export declare function externalReferenceRegistrationsPass(): CollectingPass<ReadonlyMap<string, number>>;
+/** The `r:id` each of the two element-wired references carries, or `undefined` where absent. */
+export type WorksheetReferenceRelIds = Readonly<Partial<Record<'drawing' | 'legacyDrawingHF', string>>>;
+/**
+ * A pass gathering the `r:id` of the first `<drawing>` and `<legacyDrawingHF>` in a worksheet.
+ *
+ * These two references live in the worksheet body rather than being distinguishable by relationship
+ * Type, since a header/footer VML and a comment VML share the `vmlDrawing` type, so the specific
+ * relationship is found by reading the element's own `r:id`.
+ *
+ * A pass rather than its own scan, because the sheet part is the largest in a package by a wide
+ * margin and this ran a full extra scan of it, once or twice per sheet, for two attributes.
+ * `readSheet` already builds a multi-pass single parse of it whose own comment records that five
+ * separate scans "spent 45% of a large file's read on four scans that matched no element"; this was
+ * the sixth scan, added later, that the same argument covers.
+ */
+export declare function worksheetReferencePass(): CollectingPass<WorksheetReferenceRelIds>;
+export declare function readSheetTables({ pkg }: PackageReadContext, sheetRels: PartRelationships, sheet: Worksheet, definedNames: ReadonlySet<string>): void;
+export declare function readSheetPivotTables({ pkg }: PackageReadContext, sheetRels: PartRelationships, sheet: Worksheet): void;