@shbernal/ts-xlsx 3.1.0 → 3.2.0

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

@@ -3,7 +3,7 @@ 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 './comments.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
@@ -55,5 +55,5 @@ export type WorksheetReferenceRelIds = Readonly<Partial<Record<'drawing' | 'lega
  * 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): void;
+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;

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

@@ -1,18 +1,25 @@
-import { decodeRange } from '../../core/address.js';
 import { INTERNAL } from '../../core/internal.js';
+import { mergesOverlappingTables } from '../../core/merge.js';
 import { Workbook } from '../../core/workbook.js';
 import { isAnyRelType } from '../../rel-type.js';
 import { localName } from '../../xml/xml-scan.js';
 import { relAttr } from '../opc/namespaces.js';
 import { extensionOf, resolveRelativePart } from '../opc/part-paths.js';
 import { capturePartClosure, parseRelationshipRecords, readPartRelationships, } from '../opc/read-opc.js';
-import { parseComments } from './comments.js';
-import { drawingHasUnmodeledContent, parseDrawing } from './images.js';
+import { admitting } from '../read-policy/read-repair.js';
+import { parseDrawing } from './images.js';
+import { parseComments } from './read-comments.js';
 import { parsePivotTable } from './read-pivot.js';
-import { admitting } from './read-repair.js';
+import { transitionalPart } from './strict-parts.js';
 import { parseTable } from './tables.js';
-import { parseThemeColorScheme, parseThemeFontScheme } from './theme-xml.js';
+import { parseThemeSchemes } from './theme-xml.js';
 import { buildCommentThreads, parsePersons, parseThreadedComments } from './threaded-comments.js';
+function capturePreservedClosure({ pkg, contentTypeOf }, entryPath) {
+    return capturePartClosure(entryPath, pkg.partText, pkg.partBytes, contentTypeOf)?.map((part) => {
+        const bytes = transitionalPart(part.bytes, part.contentType);
+        return bytes === part.bytes ? part : { ...part, bytes };
+    });
+}
 export function readSheetComments(sheetRels) {
     const commentsXml = sheetRels.relatedText('comments');
     return commentsXml === undefined ? undefined : parseComments(commentsXml);
@@ -23,15 +30,15 @@ export function readWorkbookPersons({ workbook }, workbookRels) {
         workbook[INTERNAL].restorePersons(parsePersons(xml));
 }
 export function readWorkbookTheme(context, workbookRels) {
-    const { pkg, contentTypeOf, workbook } = context;
+    const { pkg, workbook } = context;
     const entryPath = workbookRels.targetPath('theme');
     if (entryPath === undefined)
         return;
-    const parts = capturePartClosure(entryPath, pkg.partText, pkg.partBytes, contentTypeOf);
+    const parts = capturePreservedClosure(context, entryPath);
     if (parts === undefined)
         return;
     const xml = pkg.partText(entryPath) ?? '';
-    workbook[INTERNAL].restoreThemePart({ entryPath, parts }, { colors: parseThemeColorScheme(xml), fonts: parseThemeFontScheme(xml) });
+    workbook[INTERNAL].restoreThemePart({ entryPath, parts }, parseThemeSchemes(xml));
 }
 export function readSheetCommentThreads({ workbook }, sheetRels) {
     const xml = sheetRels.relatedText('threadedComment');
@@ -62,10 +69,11 @@ export function readSheetImages(context, sheetRels, sheet) {
     const drawingXml = partText(drawingPath);
     if (drawingXml === undefined)
         return;
-    if (drawingHasUnmodeledContent(drawingXml))
+    const { anchors, fullyModeled } = parseDrawing(drawingXml);
+    if (!fullyModeled)
         return;
     const drawingRels = readPartRelationships(drawingPath, partText);
-    for (const anchor of parseDrawing(drawingXml)) {
+    for (const anchor of anchors) {
         const embedded = drawingRels.byId(anchor.embed);
         if (embedded === undefined)
             continue;
@@ -74,15 +82,29 @@ export function readSheetImages(context, sheetRels, sheet) {
         if (id === undefined)
             continue;
         const rot = anchor.rotation !== undefined ? { rotation: anchor.rotation } : {};
+        const properties = pictureOf(anchor, drawingRels);
         if (anchor.to !== undefined) {
             const mode = anchor.editAs !== undefined ? { editAs: anchor.editAs } : {};
-            sheet.addImageAnchor(id, { from: anchor.from, to: anchor.to, ...mode, ...rot });
+            sheet.addImageAnchor(id, { from: anchor.from, to: anchor.to, ...mode, ...rot }, properties);
         }
         else if (anchor.ext !== undefined) {
-            sheet.addImageAnchor(id, { from: anchor.from, ext: anchor.ext, ...rot });
+            sheet.addImageAnchor(id, { from: anchor.from, ext: anchor.ext, ...rot }, properties);
         }
     }
 }
+function pictureOf(anchor, drawingRels) {
+    const { description, title, crop, hyperlinkId, tooltip } = anchor;
+    const link = hyperlinkId === undefined ? undefined : drawingRels.byId(hyperlinkId);
+    const target = link === undefined || link.target === '' ? undefined : link.target;
+    return {
+        ...(description === undefined ? {} : { description }),
+        ...(title === undefined ? {} : { title }),
+        ...(crop === undefined ? {} : { crop }),
+        ...(target === undefined
+            ? {}
+            : { hyperlink: tooltip === undefined ? { target } : { target, tooltip } }),
+    };
+}
 export function readSheetBackground(context, sheetRels, sheet) {
     const mediaPath = sheetRels.targetPath('image');
     if (mediaPath === undefined)
@@ -92,11 +114,9 @@ export function readSheetBackground(context, sheetRels, sheet) {
         sheet.addBackgroundImage(id);
 }
 export function readSheetPreservedReferences(context, sheetRels, referenceRelIds, sheet) {
-    const { contentTypeOf } = context;
-    const { partText, partBytes } = context.pkg;
     const capture = (element, relType, target) => {
         const entryPath = sheetRels.pathOf(target);
-        const parts = capturePartClosure(entryPath, partText, partBytes, contentTypeOf);
+        const parts = capturePreservedClosure(context, entryPath);
         if (parts !== undefined)
             sheet[INTERNAL].addPreservedReference({ element, relType, entryPath, parts });
     };
@@ -118,14 +138,13 @@ function isPreservedSheetRelType(type) {
     return isAnyRelType(type, 'pivotTable', 'slicer');
 }
 export function readWorkbookPreservedReferences(context, workbookRels, registrations) {
-    const { contentTypeOf, workbook } = context;
-    const { partText, partBytes } = context.pkg;
+    const { workbook } = context;
     const { cacheIdByRelId, externalIndexByRelId } = registrations;
     for (const record of workbookRels.records) {
         if (record.external || !isPreservedWorkbookRelType(record.type))
             continue;
         const entryPath = workbookRels.pathOf(record.target);
-        const parts = capturePartClosure(entryPath, partText, partBytes, contentTypeOf);
+        const parts = capturePreservedClosure(context, entryPath);
         if (parts === undefined)
             continue;
         const cacheId = cacheIdByRelId.get(record.id);
@@ -140,16 +159,15 @@ export function readWorkbookPreservedReferences(context, workbookRels, registrat
     }
 }
 export function readRootPreservedReferences(context) {
-    const { contentTypeOf, workbook } = context;
-    const { partText, partBytes } = context.pkg;
-    const relsXml = partText('_rels/.rels');
+    const { workbook } = context;
+    const relsXml = context.pkg.partText('_rels/.rels');
     if (relsXml === undefined)
         return;
     for (const record of parseRelationshipRecords(relsXml)) {
         if (record.external || isRegeneratedRootRelType(record.type))
             continue;
         const entryPath = resolveRelativePart('', record.target);
-        const parts = capturePartClosure(entryPath, partText, partBytes, contentTypeOf);
+        const parts = capturePreservedClosure(context, entryPath);
         if (parts === undefined)
             continue;
         workbook[INTERNAL].addPreservedRootReference({ relType: record.type, entryPath, parts });
@@ -210,12 +228,12 @@ export function worksheetReferencePass() {
         result: () => relIds,
     };
 }
-export function readSheetTables({ pkg }, sheetRels, sheet) {
+export function readSheetTables({ pkg }, sheetRels, sheet, definedNames) {
     for (const tablePath of sheetRels.targetPaths('table')) {
         const tableXml = pkg.partText(tablePath);
         if (tableXml === undefined)
             continue;
-        const options = parseTable(tableXml);
+        const options = parseTable(tableXml, definedNames);
         if (options !== undefined) {
             admitting(() => {
                 sheet.addTable(options);
@@ -235,18 +253,7 @@ export function readSheetPivotTables({ pkg }, sheetRels, sheet) {
     }
 }
 function dropMergesInsideTables(sheet) {
-    const regions = sheet.tables.map((table) => table.region);
-    if (regions.length === 0)
-        return;
-    for (const range of [...sheet.merges]) {
-        const { top, left, bottom, right } = decodeRange(range);
-        if (top === undefined || left === undefined || bottom === undefined || right === undefined)
-            continue;
-        const overlaps = regions.some((region) => left <= region.right &&
-            right >= region.left &&
-            top <= region.bottom &&
-            bottom >= region.top);
-        if (overlaps)
-            sheet.unmergeCells(range);
+    for (const { merge } of mergesOverlappingTables(sheet.merges, sheet.tables)) {
+        sheet.unmergeCells(merge);
     }
 }

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

@@ -2,6 +2,7 @@ import { isDeclarablePivotSourceKind, pivotMetricFromSubtotal, } from '../../cor
 import { numInteger } from '../../xml/xml-attrs.js';
 import { parseXml } from '../../xml/xml-read.js';
 import { localName } from '../../xml/xml-scan.js';
+import { relAttr } from '../opc/namespaces.js';
 export function parsePivotTable(tableXml, cacheXml) {
     const { fields, source } = parsePivotCacheDefinition(cacheXml);
     const def = parsePivotTableDefinition(tableXml);
@@ -20,9 +21,9 @@ export function parsePivotTable(tableXml, cacheXml) {
 }
 function parsePivotCacheDefinition(cacheXml) {
     const fields = [];
-    let source = { kind: 'worksheet', sheet: '', ref: '' };
+    let source = { kind: 'worksheet', sheet: '', ref: '', inAnotherWorkbook: false };
     parseXml(cacheXml, {
-        onOpen(name, attrs) {
+        onOpen(name, attrs, _selfClosing, scope) {
             const local = localName(name);
             if (local === 'cacheField' && attrs.name !== undefined) {
                 fields.push({ name: attrs.name });
@@ -31,7 +32,12 @@ function parsePivotCacheDefinition(cacheXml) {
                 source = { ...source, kind: sourceKind(attrs.type) };
             }
             else if (local === 'worksheetSource') {
-                source = { ...source, sheet: attrs.sheet ?? '', ref: attrs.ref ?? '' };
+                source = {
+                    ...source,
+                    sheet: attrs.sheet ?? '',
+                    ref: attrs.ref ?? '',
+                    inAnotherWorkbook: relAttr(scope, attrs, 'id') !== undefined,
+                };
             }
         },
     });

package/dist/io/xlsx/read-rich-runs.d.ts

@@ -13,19 +13,22 @@ export declare class RunAccumulator {
     #private;
     /**
      * @param options.container the element that opens one string: `'si'` for the shared-string pool,
-     * `'is'` for an inline string in a worksheet body.
-     * @param options.readRuns whether `<r>`/`<rPr>` open a rich-text run. The buffered readers read
-     * them; the row stream deliberately does not, and with runs off every `<t>` falls through to
-     * {@link plainText}, which is exactly the documented flattening.
+     * `'is'` for an inline string in a worksheet body, `'text'` for a note's body.
+     * @param options.readRuns whether `<r>`/`<rPr>` open a rich-text run. A cell's string reads them in
+     * both worksheet readers, pooled or inline; a note's body does not, and with runs off every `<t>`
+     * falls through to {@link plainText}, which is the flattening a plain-text note wants.
      */
     constructor(options: {
-        readonly container: 'si' | 'is';
+        readonly container: 'si' | 'is' | 'text';
         readonly readRuns: boolean;
     });
     /** The runs gathered so far. */
     get runs(): RichTextRun[];
     /** Whether the container held at least one `<r>`: what decides rich text from a plain string. */
     get isRich(): boolean;
+    /** Whether a container element opened at all since the last {@link beginContainer}. An `<is/>` is an
+     * empty string and a `<c t="inlineStr">` with no `<is>` is no string, and only this tells them apart. */
+    get opened(): boolean;
     /** The container's own text: every `<t>` no run claimed, concatenated and already unescaped. */
     get plainText(): string;
     /**

package/dist/io/xlsx/read-rich-runs.js

@@ -13,7 +13,9 @@ export class RunAccumulator {
     #plain = '';
     #inRun = false;
     #isRich = false;
+    #opened = false;
     #inContainer = false;
+    #phoneticDepth = 0;
     constructor(options) {
         this.#container = options.container;
         this.#readRuns = options.readRuns;
@@ -24,6 +26,9 @@ export class RunAccumulator {
     get isRich() {
         return this.#isRich;
     }
+    get opened() {
+        return this.#opened;
+    }
     get plainText() {
         return this.#plain;
     }
@@ -35,7 +40,9 @@ export class RunAccumulator {
         this.#plain = '';
         this.#inRun = false;
         this.#isRich = false;
+        this.#opened = false;
         this.#inContainer = false;
+        this.#phoneticDepth = 0;
         this.#capture.reset();
     }
     open(local, attrs, selfClosing) {
@@ -43,6 +50,7 @@ export class RunAccumulator {
             case this.#container:
                 this.beginContainer();
                 this.#inContainer = !selfClosing;
+                this.#opened = true;
                 return true;
             case 'r':
                 if (!this.#readRuns || !this.#inContainer)
@@ -59,8 +67,13 @@ export class RunAccumulator {
                 this.#font = {};
                 this.#inProperties = true;
                 return true;
+            case 'rPh':
+                if (!selfClosing)
+                    this.#phoneticDepth++;
+                return true;
             case 't':
-                this.#capture.open(local, selfClosing);
+                if (this.#phoneticDepth === 0)
+                    this.#capture.open(local, selfClosing);
                 return true;
             default:
                 if (!this.#inProperties || this.#font === null)
@@ -85,6 +98,10 @@ export class RunAccumulator {
                 }
                 return 'claimed';
             }
+            case 'rPh':
+                if (this.#phoneticDepth > 0)
+                    this.#phoneticDepth--;
+                return 'claimed';
             case 'rPr':
                 if (!this.#readRuns || !this.#inProperties)
                     return 'other';

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

@@ -1,5 +1,6 @@
 import type { CellValue } from '../../core/value.ts';
-import { type ReadPackageOptions, type XfStyle } from './read.ts';
+import type { ReadPackageOptions } from '../opc/read-options.ts';
+import type { XfStyle } from '../style/xf-style.ts';
 export interface ReadSheetRowsOptions extends ReadPackageOptions {
     /**
      * Which worksheet to stream: its name, or its 1-based position in the workbook. Defaults to the
@@ -8,9 +9,10 @@ export interface ReadSheetRowsOptions extends ReadPackageOptions {
     readonly sheet?: string | number;
 }
 /**
- * The resolved style facets of a streamed cell: its own `<c s>` cell format, flattened exactly as
- * the buffered reader resolves it. Present only when the cell carries a format; a consumer can copy
- * these straight onto a writer cell to preserve its look through a streaming read→write.
+ * The resolved style facets of a streamed cell: its own `<c s>` format, failing that its row's (when
+ * the row is marked `customFormat`), failing that its column's, flattened exactly as the buffered
+ * reader resolves it. Present only when the cell, its row or its column declares a format; a consumer
+ * can copy these straight onto a writer cell to preserve its look through a streaming read→write.
  *
  * @unpublished A named commitment this surface is not ready to make. `entries/xlsx.ts` records the
  * decision: the streaming reader's granular output shapes stay inferred structural types while the
@@ -30,7 +32,8 @@ export interface StreamedCell {
     readonly address: string;
     /** The decoded value, identical to what `readXlsx` would produce for the same cell. */
     readonly value: CellValue;
-    /** The cell's resolved style facets, or absent when the cell carries no format of its own. */
+    /** The cell's resolved style facets, including a format it inherits from its row or column; absent
+     * when none of the three declares one. */
     readonly style?: StreamedCellStyle;
 }
 /** One worksheet row, as yielded by {@link readSheetRows} / {@link StreamedSheet.rows}. */
@@ -56,13 +59,21 @@ export interface StreamedRow {
  * surface settles, so a consumer destructures them and never has to spell them.
  */
 export interface StreamedSheet {
-    /** The worksheet's declared name, joined from the workbook part. Never a positional placeholder. */
+    /**
+     * The worksheet's name, joined from the workbook part and repaired exactly as `readXlsx` repairs it
+     * (a duplicate becomes `S (2)`, a forbidden character is removed), so the two readers name a sheet
+     * the same way. Never a positional placeholder.
+     */
     readonly name: string;
     /** Stream this sheet's rows, one at a time, in sheet order. */
     rows(): Generator<StreamedRow, void, undefined>;
     /** 1-based indices of columns the sheet declares hidden, ascending. */
     readonly hiddenColumns: readonly number[];
-    /** The sheet's merged ranges, as canonical A1 range strings, in declaration order. */
+    /**
+     * The sheet's merged ranges, as canonical A1 range strings, in declaration order: the ones
+     * `readXlsx` admits, so an unreadable range, or one overlapping a range declared before it, is
+     * dropped.
+     */
     readonly merges: readonly string[];
 }
 /**