@shbernal/ts-xlsx 3.0.0 → 3.2.0

package/dist/io/xlsx/write.js

@@ -1,13 +1,17 @@
 import { strToU8, zip, zipSync } from 'fflate';
-import { AuthoringError } from '../../errors.js';
-import { relativePartPath, relsPathFor, THEME_PART_PATH } from '../opc/part-paths.js';
+import { formulaNamesInScope } from '../../core/formula.js';
+import { pictureProperties } from '../../core/image.js';
+import { AuthoringError, InternalError, quoted } from '../../errors.js';
+import { isRelType } from '../../rel-type.js';
+import { relsPathFor, THEME_PART_PATH } from '../opc/part-paths.js';
 import { relsPartXml } from '../opc/rels.js';
 import { FIXED_ENTRY_MTIME } from '../opc/zip-mtime.js';
-import { collectComments, commentsXml, vmlDrawingXml } from './comments.js';
-import { collectHyperlinks, planHyperlinks } from './hyperlinks.js';
-import { drawingRelsXml, drawingXml } from './images.js';
-import { planMedia, planPreservedParts, SheetRelIds, } from './package-plan.js';
-import { APP_PROPS_PART, commentsPart, CORE_PROPS_PART, drawingPart, mediaPart, PERSONS_PART, pivotCacheDefinitionPart, pivotCacheRecordsPart, pivotTablePart, printerSettingsPart, SHARED_STRINGS_PART, STYLES_PART, tablePart, threadedCommentsPart, vmlDrawingPart, WORKBOOK_PART, worksheetPart, } from './part-names.js';
+import { RICH_VALUE_STRUCTURES_XML, WorkbookMetadataTable } from './cell-metadata.js';
+import { collectComments, commentsXml, liveCells, vmlDrawingXml } from './comments.js';
+import { planHyperlinks } from './hyperlinks.js';
+import { drawingXml } from './images.js';
+import { planMedia, planPreservedParts, RelationshipLedger, } from './package-plan.js';
+import { APP_PROPS_PART, commentsPart, CORE_PROPS_PART, drawingPart, mediaPart, METADATA_PART, PERSONS_PART, pivotCacheDefinitionPart, pivotCacheRecordsPart, pivotTablePart, printerSettingsPart, RICH_VALUE_STRUCTURES_PART, RICH_VALUES_PART, SHARED_STRINGS_PART, STYLES_PART, tablePart, threadedCommentsPart, vmlDrawingPart, WORKBOOK_PART, worksheetPart, } from './part-names.js';
 import { pivotCacheDefinitionXml, pivotCacheRecordsXml, pivotTableXml } from './pivot.js';
 import { REL } from './relationships.js';
 import { SharedStringTable } from './shared-strings.js';
@@ -15,9 +19,8 @@ import { StyleRegistry } from './styles.js';
 import { tableXml } from './tables.js';
 import { applyThemeOverrides, DEFAULT_THEME_XML } from './theme-xml.js';
 import { personsXml, threadedCommentsXml } from './threaded-comments.js';
-import { appPropsXml, contentTypesXml, corePropsXml, FIXED_WORKBOOK_REL_COUNT, rootRelsXml, workbookRelsXml, workbookXml, } from './workbook-xml.js';
-import { worksheetRelsXml, worksheetXml, } from './worksheet-xml.js';
-export { buildColumnDefaults, Extent, renderRow, } from './worksheet-xml.js';
+import { appPropsXml, contentTypesXml, corePropsXml, workbookXml, } from './workbook-xml.js';
+import { worksheetXml } from './worksheet-xml.js';
 export function writeXlsx(workbook, options = {}) {
     return zipSync(buildPackageParts(workbook, options), { level: 6, mtime: FIXED_ENTRY_MTIME });
 }
@@ -48,52 +51,77 @@ export function createStyleRegistry(workbook) {
         styles.addTableStyle(style);
     return styles;
 }
+function keptDrawingPath(sheet) {
+    return sheet.preservedReferences.find((reference) => reference.element === 'drawing')?.entryPath;
+}
+function drawingImages(sheet, media, drawingRels) {
+    return sheet.images.map((image) => {
+        const { number: mediaNumber, image: registered } = media.resolve(image.imageId);
+        const embedId = drawingRels.add(REL.image, mediaPart(mediaNumber, registered.extension));
+        const properties = pictureProperties(image);
+        const target = properties.hyperlink?.target;
+        if (target === undefined)
+            return { anchor: image.anchor, embedId, properties };
+        const hyperlinkId = target.startsWith('#')
+            ? drawingRels.addInDocument(REL.hyperlink, target)
+            : drawingRels.addExternal(REL.hyperlink, target);
+        return { anchor: image.anchor, embedId, properties, hyperlinkId };
+    });
+}
 function planSheet(context) {
-    const { sheet, index, media, preserved, numbering } = context;
-    const rels = new SheetRelIds();
-    const tables = sheet.tables.map((table) => ({
-        table,
-        number: ++numbering.table,
-        relId: rels.next(),
-    }));
+    const { sheet, index, media, preserved, numbering, flushed } = context;
+    const rels = new RelationshipLedger(worksheetPart(index + 1));
+    const tables = sheet.tables.map((table) => {
+        const number = ++numbering.table;
+        return { table, number, relId: rels.add(REL.table, tablePart(number)) };
+    });
     let drawing = null;
-    if (sheet.images.length > 0) {
-        const images = sheet.images.map((image, j) => {
-            const { number, image: registered } = media.resolve(image.imageId);
-            return {
-                anchor: image.anchor,
-                embedId: `rId${j + 1}`,
-                mediaNumber: number,
-                extension: registered.extension,
-            };
-        });
-        drawing = { number: ++numbering.drawing, relId: rels.next(), images };
+    if (sheet.images.length > 0 && keptDrawingPath(sheet) === undefined) {
+        const number = ++numbering.drawing;
+        const path = drawingPart(number);
+        const drawingRels = new RelationshipLedger(path);
+        drawing = {
+            number,
+            relId: rels.add(REL.drawing, path),
+            images: drawingImages(sheet, media, drawingRels),
+            relationships: drawingRels.relationships,
+        };
     }
     const threads = sheet.commentThreads.filter((thread) => thread.comments.length > 0);
-    const sheetComments = collectComments(sheet, threads);
-    const comments = sheetComments.length === 0
+    const sheetComments = collectComments(liveCells(sheet), threads, flushed?.notes ?? []);
+    let comments = null;
+    if (sheetComments.length > 0) {
+        const vmlRelId = rels.add(REL.vmlDrawing, vmlDrawingPart(index + 1));
+        rels.add(REL.comments, commentsPart(index + 1));
+        comments = { number: index + 1, comments: sheetComments, vmlRelId };
+    }
+    let threadedComments = null;
+    if (threads.length > 0) {
+        rels.add(REL.threadedComment, threadedCommentsPart(index + 1));
+        threadedComments = { number: index + 1, threads };
+    }
+    const printerData = sheet.pageSetup.printerSettings;
+    const printerSettings = printerData === undefined
         ? null
         : {
             number: index + 1,
-            comments: sheetComments,
-            vmlRelId: rels.next(),
-            commentsRelId: rels.next(),
+            data: printerData,
+            relId: rels.add(REL.printerSettings, printerSettingsPart(index + 1)),
         };
-    const threadedComments = threads.length === 0 ? null : { number: index + 1, threads, relId: rels.next() };
-    const printerData = sheet.pageSetup.printerSettings;
-    const printerSettings = printerData === undefined ? null : { number: index + 1, data: printerData, relId: rels.next() };
-    const hyperlinks = planHyperlinks(collectHyperlinks(sheet), rels);
+    const hyperlinks = planHyperlinks(sheet.hyperlinks, rels);
     let background = null;
     if (sheet.backgroundImageId !== undefined) {
         const { number, image } = media.resolve(sheet.backgroundImageId);
-        background = { relId: rels.next(), mediaNumber: number, extension: image.extension };
+        background = { relId: rels.add(REL.image, mediaPart(number, image.extension)) };
     }
-    const preservedRefs = (preserved.perSheet[index] ?? []).map((reference) => ({ ...reference, relId: rels.next() }));
+    const preservedRefs = (preserved.perSheet[index] ?? []).map((reference) => ({ ...reference, relId: rels.add(reference.relType, reference.entryPath) }));
     const pivots = sheet.pivotTables.map((table) => {
         const number = ++numbering.pivot;
-        return { number, cacheId: String(number), table, sheetRelId: rels.next(), workbookRelId: '' };
+        rels.add(REL.pivotTable, pivotTablePart(number));
+        return { number, cacheId: String(number), table, workbookRelId: '' };
     });
     return {
+        relationships: rels.relationships,
         tables,
         drawing,
         comments,
@@ -119,7 +147,7 @@ function resolveSheetReferences(plan) {
     const preservedDrawingRelId = refs.find((ref) => ref.element === 'drawing')?.relId ?? null;
     const legacyDrawingHFRelId = refs.find((ref) => ref.element === 'legacyDrawingHF')?.relId ?? null;
     const slicerRelIds = refs
-        .filter((ref) => ref.relType.endsWith('/slicer'))
+        .filter((ref) => isRelType(ref.relType, 'slicer'))
         .map((ref) => ref.relId);
     return {
         drawingRelId: plan.drawing?.relId ?? preservedDrawingRelId,
@@ -130,27 +158,57 @@ function resolveSheetReferences(plan) {
         slicerRelIds,
     };
 }
-function assignWorkbookRelIds(context) {
-    const { sheetCount, hasSharedStrings, hasPersons, preservedWorkbook, pivots } = context;
-    const modeledCount = sheetCount + FIXED_WORKBOOK_REL_COUNT + (hasSharedStrings ? 1 : 0);
-    const personsRelId = hasPersons ? `rId${modeledCount + 1}` : null;
-    const preservedBase = modeledCount + (personsRelId === null ? 0 : 1);
-    const preservedWorkbookRels = preservedWorkbook.map((ref, i) => ({
+function planWorkbookRelationships(context) {
+    const { sheetCount, hasSharedStrings, hasPersons, hasCellMetadata, hasRichValues, preservedWorkbook, pivots, } = context;
+    const rels = new RelationshipLedger(WORKBOOK_PART);
+    const sheetRelIds = Array.from({ length: sheetCount }, (_, i) => rels.add(REL.worksheet, worksheetPart(i + 1)));
+    rels.add(REL.styles, STYLES_PART);
+    rels.add(REL.theme, THEME_PART_PATH);
+    if (hasSharedStrings)
+        rels.add(REL.sharedStrings, SHARED_STRINGS_PART);
+    if (hasPersons)
+        rels.add(REL.person, PERSONS_PART);
+    if (hasCellMetadata)
+        rels.add(REL.sheetMetadata, METADATA_PART);
+    if (hasRichValues) {
+        rels.add(REL.rdRichValue, RICH_VALUES_PART);
+        rels.add(REL.rdRichValueStructure, RICH_VALUE_STRUCTURES_PART);
+    }
+    const preservedWorkbookRels = preservedWorkbook.map((ref) => ({
         ...ref,
-        relId: `rId${preservedBase + 1 + i}`,
+        relId: rels.add(ref.relType, ref.entryPath),
     }));
-    const pivotBase = preservedBase + preservedWorkbook.length;
-    pivots.forEach((pivot, i) => {
-        pivot.workbookRelId = `rId${pivotBase + 1 + i}`;
-    });
-    return { personsRelId, preservedWorkbookRels };
+    for (const pivot of pivots) {
+        pivot.workbookRelId = rels.add(REL.pivotCacheDefinition, pivotCacheDefinitionPart(pivot.number));
+    }
+    return { sheetRelIds, preservedWorkbookRels, relationships: rels.relationships };
 }
-function planPackage(workbook, sheets) {
+function planRootRelationships(rootRefs) {
+    const rels = new RelationshipLedger('');
+    rels.add(REL.officeDocument, WORKBOOK_PART);
+    rels.add(REL.coreProps, CORE_PROPS_PART);
+    rels.add(REL.extProps, APP_PROPS_PART);
+    for (const ref of rootRefs)
+        rels.add(ref.relType, ref.entryPath);
+    return rels.relationships;
+}
+function planPackage(workbook, sheets, flushed) {
     const media = planMedia(workbook, sheets);
-    const generatedDrawingCount = sheets.filter((sheet) => sheet.images.length > 0).length;
-    const preserved = planPreservedParts(workbook, generatedDrawingCount, media.parts.length);
+    const pictures = new Map();
+    let generatedDrawingCount = 0;
+    for (const sheet of sheets) {
+        if (sheet.images.length === 0)
+            continue;
+        const kept = keptDrawingPath(sheet);
+        if (kept === undefined)
+            generatedDrawingCount += 1;
+        else
+            pictures.set(kept, (ledger) => drawingImages(sheet, media, ledger));
+    }
+    const generatedPivotCount = sheets.reduce((total, sheet) => total + sheet.pivotTables.length, 0);
+    const preserved = planPreservedParts(workbook, generatedDrawingCount, media.parts.length, generatedPivotCount, pictures);
     const numbering = { table: 0, drawing: 0, pivot: 0 };
-    const perSheet = sheets.map((sheet, index) => planSheet({ sheet, index, media, preserved, numbering }));
+    const perSheet = sheets.map((sheet, index) => planSheet({ sheet, index, media, preserved, numbering, flushed: flushed?.get(sheet) }));
     return {
         media,
         preserved,
@@ -159,58 +217,99 @@ function planPackage(workbook, sheets) {
         allPivots: perSheet.flatMap((plan) => plan.pivots),
     };
 }
-function serialiseSheets(workbook, sheets, plan, styles, sharedStrings, flushed) {
+function serialiseSheets(context) {
+    const { workbook, sheets, plan, styles, sharedStrings, cellMetadata, flushed } = context;
     return sheets.map((sheet, i) => {
         const sheetPlan = plan.perSheet[i];
-        return worksheetXml(sheet, sheetPlan.tables, styles, resolveSheetReferences(sheetPlan), sheetPlan.hyperlinks, sharedStrings, i === workbook.activeTabIndex, flushed?.get(sheet));
+        return worksheetXml({
+            sheet,
+            tables: sheetPlan.tables,
+            styles,
+            references: resolveSheetReferences(sheetPlan),
+            hyperlinks: sheetPlan.hyperlinks,
+            sharedStrings,
+            cellMetadata,
+            dateEpoch: workbook.dateEpoch,
+            formulaNames: formulaNamesInScope(workbook.definedNames, sheet.name),
+            active: i === workbook.activeTabIndex,
+            flushed: flushed?.get(sheet),
+        });
     });
 }
 function emitPackageParts(context) {
-    const { workbook, sheets, plan, styles, sharedStrings, sheetXml } = context;
+    const { workbook, sheets, plan, styles, sharedStrings, cellMetadata, sheetXml } = context;
     const { media, preserved, perSheet, allTables, allPivots } = plan;
     const hasSharedStrings = sharedStrings !== null && !sharedStrings.isEmpty;
+    const hasCellMetadata = !cellMetadata.isEmpty;
+    const hasRichValues = cellMetadata.hasRichValues;
     const commentNumbers = numbersOf(perSheet, (sheetPlan) => sheetPlan.comments);
     const drawingNumbers = numbersOf(perSheet, (sheetPlan) => sheetPlan.drawing);
     const printerSettingsNumbers = numbersOf(perSheet, (sheetPlan) => sheetPlan.printerSettings);
     const threadedCommentNumbers = numbersOf(perSheet, (sheetPlan) => sheetPlan.threadedComments);
     const persons = threadedCommentNumbers.length === 0 ? [] : workbook.persons;
-    const { personsRelId, preservedWorkbookRels } = assignWorkbookRelIds({
+    const workbookRels = planWorkbookRelationships({
         sheetCount: sheets.length,
         hasSharedStrings,
         hasPersons: persons.length > 0,
+        hasCellMetadata,
+        hasRichValues,
         preservedWorkbook: preserved.workbook,
         pivots: allPivots,
     });
-    const files = {
-        '[Content_Types].xml': strToU8(contentTypesXml(sheets.length, allTables, commentNumbers, drawingNumbers, printerSettingsNumbers, media.extensions, hasSharedStrings, preserved.parts, allPivots, preservedWorkbookRels, threadedCommentNumbers, persons.length > 0)),
-        '_rels/.rels': strToU8(rootRelsXml(preserved.root)),
-        [CORE_PROPS_PART]: strToU8(corePropsXml(workbook.properties)),
-        [APP_PROPS_PART]: strToU8(appPropsXml(workbook.properties)),
-        [WORKBOOK_PART]: strToU8(workbookXml(workbook, preservedWorkbookRels, allPivots)),
-        [relsPathFor(WORKBOOK_PART)]: strToU8(workbookRelsXml(sheets.length, hasSharedStrings, personsRelId, preservedWorkbookRels, allPivots)),
-        [STYLES_PART]: strToU8(styles.toXml()),
-    };
+    const { preservedWorkbookRels } = workbookRels;
+    const files = new PackageFiles();
+    files.add('[Content_Types].xml', strToU8(contentTypesXml({
+        sheetCount: sheets.length,
+        tables: allTables,
+        commentNumbers,
+        drawingNumbers,
+        printerSettingsNumbers,
+        mediaExtensions: media.extensions,
+        hasSharedStrings,
+        preservedParts: preserved.parts,
+        pivots: allPivots,
+        preservedWorkbookRefs: preservedWorkbookRels,
+        threadedCommentNumbers,
+        hasPersons: persons.length > 0,
+        hasCellMetadata,
+        hasRichValues,
+    })));
+    files.add(relsPathFor(''), strToU8(relsPartXml(planRootRelationships(preserved.root))));
+    files.add(CORE_PROPS_PART, strToU8(corePropsXml(workbook.properties)));
+    files.add(APP_PROPS_PART, strToU8(appPropsXml(workbook.properties)));
+    files.add(WORKBOOK_PART, strToU8(workbookXml(workbook, workbookRels, allPivots)));
+    files.add(relsPathFor(WORKBOOK_PART), strToU8(relsPartXml(workbookRels.relationships)));
+    files.add(STYLES_PART, strToU8(styles.toXml()));
     if (!preserved.themeEmitted) {
         const overrides = workbook.themeOverrides;
-        files[THEME_PART_PATH] = strToU8(overrides === undefined
+        files.add(THEME_PART_PATH, strToU8(overrides === undefined
             ? DEFAULT_THEME_XML
-            : applyThemeOverrides(DEFAULT_THEME_XML, overrides));
+            : applyThemeOverrides(DEFAULT_THEME_XML, overrides)));
     }
     if (hasSharedStrings) {
-        files[SHARED_STRINGS_PART] = strToU8(sharedStrings.toXml());
+        files.add(SHARED_STRINGS_PART, strToU8(sharedStrings.toXml()));
     }
     if (persons.length > 0)
-        files[PERSONS_PART] = strToU8(personsXml(persons));
-    for (const part of media.parts) {
-        files[mediaPart(part.number, part.extension)] = part.data;
+        files.add(PERSONS_PART, strToU8(personsXml(persons)));
+    if (hasCellMetadata)
+        files.add(METADATA_PART, strToU8(cellMetadata.toXml()));
+    if (hasRichValues) {
+        files.add(RICH_VALUES_PART, strToU8(cellMetadata.richValuesXml()));
+        files.add(RICH_VALUE_STRUCTURES_PART, strToU8(RICH_VALUE_STRUCTURES_XML));
     }
-    emitSheetParts(files, perSheet, sheetXml);
-    for (const { table, number } of allTables) {
-        files[tablePart(number)] = strToU8(tableXml(table, number));
+    for (const part of media.parts) {
+        files.add(mediaPart(part.number, part.extension), part.data);
     }
+    emitSheetParts(files, perSheet, sheetXml, (id) => workbook.getPerson(id));
+    perSheet.forEach(({ tables }, index) => {
+        const formulaNames = formulaNamesInScope(workbook.definedNames, sheets[index]?.name);
+        for (const { table, number } of tables) {
+            files.add(tablePart(number), strToU8(tableXml(table, number, formulaNames)));
+        }
+    });
     emitPivotParts(files, allPivots);
     emitPreservedParts(files, preserved.parts);
-    return files;
+    return files.toRecord();
 }
 export function buildPackageParts(workbook, options = {}) {
     const sheets = workbook.worksheets;
@@ -219,41 +318,52 @@ export function buildPackageParts(workbook, options = {}) {
     }
     const sharedStrings = options.useSharedStrings ? new SharedStringTable() : null;
     const styles = options.styles ?? createStyleRegistry(workbook);
-    const plan = planPackage(workbook, sheets);
-    const sheetXml = serialiseSheets(workbook, sheets, plan, styles, sharedStrings, options.flushed);
-    return emitPackageParts({ workbook, sheets, plan, styles, sharedStrings, sheetXml });
+    const cellMetadata = options.cellMetadata ?? new WorkbookMetadataTable();
+    const plan = planPackage(workbook, sheets, options.flushed);
+    const sheetXml = serialiseSheets({
+        workbook,
+        sheets,
+        plan,
+        styles,
+        sharedStrings,
+        cellMetadata,
+        flushed: options.flushed,
+    });
+    return emitPackageParts({ workbook, sheets, plan, styles, sharedStrings, cellMetadata, sheetXml });
+}
+class PackageFiles {
+    #files = Object.create(null);
+    add(path, bytes) {
+        if (path in this.#files) {
+            throw new InternalError(`two package parts claim the path ${quoted(path)}`);
+        }
+        this.#files[path] = bytes;
+    }
+    toRecord() {
+        return this.#files;
+    }
 }
-function emitSheetParts(files, perSheet, sheetXml) {
+function emitSheetParts(files, perSheet, sheetXml, personById) {
     perSheet.forEach((plan, i) => {
-        const { tables, drawing, comments, threadedComments, printerSettings, background, hyperlinks, preservedRefs, pivots, } = plan;
-        const hasExternalHyperlink = hyperlinks.some((link) => link.relId !== undefined);
-        files[worksheetPart(i + 1)] = strToU8(sheetXml[i]);
-        if (tables.length > 0 ||
-            drawing !== null ||
-            comments !== null ||
-            threadedComments !== null ||
-            printerSettings !== null ||
-            background !== null ||
-            hasExternalHyperlink ||
-            preservedRefs.length > 0 ||
-            pivots.length > 0) {
-            files[relsPathFor(worksheetPart(i + 1))] = strToU8(worksheetRelsXml(tables, drawing, comments, threadedComments, printerSettings, background, hyperlinks, preservedRefs, pivots));
+        const { relationships, drawing, comments, threadedComments, printerSettings } = plan;
+        files.add(worksheetPart(i + 1), strToU8(sheetXml[i]));
+        if (relationships.length > 0) {
+            files.add(relsPathFor(worksheetPart(i + 1)), strToU8(relsPartXml(relationships)));
         }
         if (printerSettings !== null) {
-            files[printerSettingsPart(printerSettings.number)] = printerSettings.data;
+            files.add(printerSettingsPart(printerSettings.number), printerSettings.data);
         }
         if (drawing !== null) {
             const drawingPath = drawingPart(drawing.number);
-            files[drawingPath] = strToU8(drawingXml(drawing.images));
-            const targets = drawing.images.map((image) => relativePartPath(drawingPath, mediaPart(image.mediaNumber, image.extension)));
-            files[relsPathFor(drawingPath)] = strToU8(drawingRelsXml(targets));
+            files.add(drawingPath, strToU8(drawingXml(drawing.images)));
+            files.add(relsPathFor(drawingPath), strToU8(relsPartXml(drawing.relationships)));
         }
         if (comments !== null) {
-            files[commentsPart(comments.number)] = strToU8(commentsXml(comments.comments));
-            files[vmlDrawingPart(comments.number)] = strToU8(vmlDrawingXml(comments.comments));
+            files.add(commentsPart(comments.number), strToU8(commentsXml(comments.comments)));
+            files.add(vmlDrawingPart(comments.number), strToU8(vmlDrawingXml(comments.comments)));
         }
         if (threadedComments !== null) {
-            files[threadedCommentsPart(threadedComments.number)] = strToU8(threadedCommentsXml(threadedComments.threads));
+            files.add(threadedCommentsPart(threadedComments.number), strToU8(threadedCommentsXml(threadedComments.threads, personById)));
         }
     });
 }
@@ -262,30 +372,23 @@ function emitPivotParts(files, allPivots) {
         const { number, cacheId, table } = pivot;
         const tablePath = pivotTablePart(number);
         const definitionPath = pivotCacheDefinitionPart(number);
-        files[tablePath] = strToU8(pivotTableXml(table, `PivotTable${number}`, cacheId));
-        files[relsPathFor(tablePath)] = strToU8(relsPartXml([
-            {
-                id: 'rId1',
-                type: REL.pivotCacheDefinition,
-                target: relativePartPath(tablePath, definitionPath),
-            },
-        ]));
-        files[definitionPath] = strToU8(pivotCacheDefinitionXml(table));
-        files[relsPathFor(definitionPath)] = strToU8(relsPartXml([
-            {
-                id: 'rId1',
-                type: REL.pivotCacheRecords,
-                target: relativePartPath(definitionPath, pivotCacheRecordsPart(number)),
-            },
-        ]));
-        files[pivotCacheRecordsPart(number)] = strToU8(pivotCacheRecordsXml(table));
+        const recordsPath = pivotCacheRecordsPart(number);
+        const tableRels = new RelationshipLedger(tablePath);
+        tableRels.add(REL.pivotCacheDefinition, definitionPath);
+        files.add(tablePath, strToU8(pivotTableXml(table, `PivotTable${number}`, cacheId)));
+        files.add(relsPathFor(tablePath), strToU8(relsPartXml(tableRels.relationships)));
+        const definitionRels = new RelationshipLedger(definitionPath);
+        const recordsRelId = definitionRels.add(REL.pivotCacheRecords, recordsPath);
+        files.add(definitionPath, strToU8(pivotCacheDefinitionXml(table, recordsRelId)));
+        files.add(relsPathFor(definitionPath), strToU8(relsPartXml(definitionRels.relationships)));
+        files.add(recordsPath, strToU8(pivotCacheRecordsXml(table)));
     }
 }
 function emitPreservedParts(files, parts) {
     for (const part of parts) {
-        files[part.path] = part.bytes;
+        files.add(part.path, part.bytes);
         if (part.relsPath !== null && part.relsXml !== null) {
-            files[part.relsPath] = strToU8(part.relsXml);
+            files.add(part.relsPath, strToU8(part.relsXml));
         }
     }
 }

package/dist/rel-type.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The last segment of a relationship Type (`vbaProjectSignatureAgile` in
+ * `http://schemas.microsoft.com/office/2014/relationships/vbaProjectSignatureAgile`), or the whole Type
+ * when it has no `/`: for a caller that looks the segment up rather than testing for one class.
+ *
+ * {@link isRelType} is not built on it, because a class name may span segments: the ribbon's is
+ * `ui/extensibility`.
+ */
+export declare function relTypeSegment(type: string): string;
+/**
+ * Does a relationship Type name this class of part?
+ *
+ * A Type is a URI whose last segment names the part class, and the namespace in front of it varies by
+ * relationship family and by the schema version a producer wrote against. So the match is on that
+ * last segment.
+ *
+ * **The separator is the load-bearing character.** `/slicer` and `slicer` are not the same test:
+ * without the slash, `slicer` matches `slicerCache`, `table` matches `pivotTable`, and a lookup
+ * quietly gathers a part class nobody asked for. Every caller used to spell the slash itself, ten
+ * times over, with nowhere to say why it was there.
+ */
+export declare function isRelType(type: string, name: string): boolean;
+/** {@link isRelType} against several part classes at once, for the predicates that partition
+ * relationships into "modeled", "preserved verbatim", and "dropped". */
+export declare function isAnyRelType(type: string, ...names: readonly string[]): boolean;

package/dist/rel-type.js

@@ -0,0 +1,9 @@
+export function relTypeSegment(type) {
+    return type.slice(type.lastIndexOf('/') + 1);
+}
+export function isRelType(type, name) {
+    return type.endsWith(`/${name}`);
+}
+export function isAnyRelType(type, ...names) {
+    return names.some((name) => isRelType(type, name));
+}

package/dist/token-set.d.ts

@@ -13,3 +13,16 @@
  * expression instead of as its members.
  */
 export declare function tokenSet<T extends string>(members: Record<T, true>): (value: string) => value is T;
+/**
+ * {@link tokenSet} for a union whose members are also needed as an ordered *list*, because a binary
+ * serialisation indexes one.
+ *
+ * The record form's whole guarantee is that a member cannot be omitted, and a list gives that up: it
+ * can name only members of the union, but it can name fewer. So a caller here owes an explicit proof
+ * of set equality in both directions, which is what `FILL_PATTERNS_IN_SCHEMA_ORDER` carries beside
+ * itself. That is a worse guarantee than the record's, taken deliberately: the alternative is the
+ * arrangement it replaced, where the union, the guard's table and the binary codec's index list were
+ * three hand-maintained copies of one enumeration and only two of them were checked against each
+ * other.
+ */
+export declare function tokenSetOf<T extends string>(members: readonly T[]): (value: string) => value is T;

package/dist/token-set.js

@@ -1,4 +1,7 @@
 export function tokenSet(members) {
-    const set = new Set(Object.keys(members));
+    return tokenSetOf(Object.keys(members));
+}
+export function tokenSetOf(members) {
+    const set = new Set(members);
     return (value) => set.has(value);
 }

package/dist/vba/bytes.d.ts

@@ -1,11 +1,22 @@
-export { concat } from '../bytes.ts';
+export { concat, decodeUtf16le } from '../bytes.ts';
 /** Read a little-endian `uint16`. @throws {VbaParseError} if the two bytes are not both in `buf`. */
 export declare function readU16(buf: Uint8Array, at: number): number;
 /** Read a little-endian `uint32`. @throws {VbaParseError} if the four bytes are not all in `buf`. */
 export declare function readU32(buf: Uint8Array, at: number): number;
 /**
- * Decode UTF-16LE code units: the encoding [MS-CFB] uses for directory-entry names and [MS-OVBA] for
- * every "Unicode" name field. A trailing odd byte is dropped: these fields are length-prefixed by the
- * producer and a half code unit carries nothing to decode.
+ * Write a little-endian `uint16` over bytes already in `buf`. The value is asserted rather than
+ * masked: a caller that arrived at `-1` or `0x1_0000` has miscounted something, and silently storing
+ * `0xffff` turns that into a `dir` stream declaring 65,535 modules.
  */
-export declare function decodeUtf16le(bytes: Uint8Array): string;
+export declare function writeU16(buf: Uint8Array, at: number, value: number): void;
+/** Write a little-endian `uint32` over bytes already in `buf`, asserted rather than masked as {@link writeU16} is. */
+export declare function writeU32(buf: Uint8Array, at: number, value: number): void;
+/**
+ * Replace `src[start..end)` with `insert`, returning a new array.
+ *
+ * The three record edits the project editor makes are all this shape: splice a MODULE record block in,
+ * cut one out, cut a PROJECTwm entry out. Each was an allocate-and-copy-around written out longhand,
+ * and each had to get the same three offsets right; saying it once means the arithmetic is checked
+ * once. Passing no `insert` is a pure deletion, and `start === end` a pure insertion.
+ */
+export declare function spliceBytes(src: Uint8Array, start: number, end: number, insert?: Uint8Array): Uint8Array;

package/dist/vba/bytes.js

@@ -1,4 +1,4 @@
-export { concat } from '../bytes.js';
+export { concat, decodeUtf16le } from '../bytes.js';
 import { VbaParseError } from './errors.js';
 function truncated(at, need, length) {
     return new VbaParseError(`read of ${need} bytes at offset ${at} runs past the end of a ${length}-byte buffer`);
@@ -20,10 +20,31 @@ export function readU32(buf, at) {
     }
     return (b0 | (b1 << 8) | (b2 << 16) | (b3 << 24)) >>> 0;
 }
-export function decodeUtf16le(bytes) {
-    let s = '';
-    for (let i = 0; i + 1 < bytes.length; i += 2) {
-        s += String.fromCharCode(readU16(bytes, i));
+export function writeU16(buf, at, value) {
+    if (!Number.isInteger(value) || value < 0 || value > 0xffff) {
+        throw new VbaParseError(`${value} does not fit the uint16 at offset ${at}`);
     }
-    return s;
+    if (at + 1 >= buf.length)
+        throw truncated(at, 2, buf.length);
+    buf[at] = value & 0xff;
+    buf[at + 1] = (value >> 8) & 0xff;
+}
+export function writeU32(buf, at, value) {
+    if (!Number.isInteger(value) || value < 0 || value > 0xffff_ffff) {
+        throw new VbaParseError(`${value} does not fit the uint32 at offset ${at}`);
+    }
+    if (at + 3 >= buf.length)
+        throw truncated(at, 4, buf.length);
+    buf[at] = value & 0xff;
+    buf[at + 1] = (value >>> 8) & 0xff;
+    buf[at + 2] = (value >>> 16) & 0xff;
+    buf[at + 3] = (value >>> 24) & 0xff;
+}
+export function spliceBytes(src, start, end, insert = EMPTY) {
+    const out = new Uint8Array(src.length - (end - start) + insert.length);
+    out.set(src.subarray(0, start), 0);
+    out.set(insert, start);
+    out.set(src.subarray(end), start + insert.length);
+    return out;
 }
+const EMPTY = new Uint8Array(0);