@shbernal/ts-xlsx 1.2.0 → 2.0.0

package/README.md

@@ -236,6 +236,11 @@ npx skills add ./node_modules/@shbernal/ts-xlsx     # offline, matches your inst
 npx skills add shbernal/ts-xlsx                     # or straight from the repo
 ```
 
+That writes the skill under `.agents/skills/`, links it into whichever agent directories it
+finds, and records what it did in `skills-lock.json`. Track the lock file and ignore the
+copies: they are derived, `npx skills experimental_install` rebuilds them from the lock, and
+`npx skills update` overwrites them in place.
+
 It covers triage (is this bug ours or your file's?), reducing a failure to a script that
 builds its own input, and — because spreadsheets carry real data — never uploading a
 workbook to a public tracker. Once the reproduction stands on its own, it files without

package/dist/core/address.d.ts

@@ -2,9 +2,33 @@
 export declare const MAX_COLUMN = 16384;
 /** Excel's row bound: 1 through 1048576. The other axis of {@link MAX_COLUMN}. */
 export declare const MAX_ROW = 1048576;
+/** @throws {RangeError} unless `n` is an integer in `1..MAX_COLUMN`. */
+export declare function assertColumnInBounds(n: number): void;
+/** @throws {RangeError} unless `n` is an integer in `1..MAX_ROW`. */
+export declare function assertRowInBounds(n: number): void;
+/**
+ * A rectangular block of the grid, as **inclusive** 1-based bounds on both axes.
+ *
+ * One declaration because inclusive-first/last is the convention every range-shaped thing in this
+ * library follows, and three copies of a convention are three places it can drift. A merged region,
+ * a table's extent and a {@link Range} handle are all this shape; what differs between them is what
+ * the rectangle *means*, which is what their own names carry.
+ */
+export interface GridRect {
+    /** 1-based row of the top edge. */
+    readonly top: number;
+    /** 1-based column of the left edge. */
+    readonly left: number;
+    /** 1-based row of the bottom edge, inclusive. */
+    readonly bottom: number;
+    /** 1-based column of the right edge, inclusive. */
+    readonly right: number;
+}
+/** Whether two grid rectangles share at least one cell. */
+export declare function rectsOverlap(a: GridRect, b: GridRect): boolean;
 /** A decoded single-cell reference. An axis the reference omits is `undefined`. */
 export interface CellAddress {
-    /** Canonical A1 form with `$` anchors stripped — e.g. `"B2"`, `"1"`, `"A"`. */
+    /** Canonical A1 form with `$` anchors stripped: e.g. `"B2"`, `"1"`, `"A"`. */
     readonly address: string;
     /** 1-based column, or `undefined` for a row-only reference (`$1`). */
     readonly col: number | undefined;
@@ -25,7 +49,7 @@ export interface RangeAddress {
     readonly sheetName?: string;
     readonly tl: CellAddress;
     readonly br: CellAddress;
-    /** Canonical `tl:br` form — `"A1:B2"`, `"1:1"` (rows), `"A:A"` (columns). */
+    /** Canonical `tl:br` form: `"A1:B2"`, `"1:1"` (rows), `"A:A"` (columns). */
     readonly dimensions: string;
 }
 /** Convert a 1-based column number to its letters (`1 → "A"`, `27 → "AA"`). */
@@ -39,6 +63,29 @@ export declare function columnToNumber(letters: string): number;
  * @throws {SyntaxError} if the reference mentions neither a column nor a row.
  */
 export declare function decodeAddress(reference: string): CellAddress;
+/**
+ * A reference that names one cell, both axes present. The narrowing of {@link CellAddress} that
+ * most callers actually want: `decodeAddress` is deliberately three-shaped because a bare row
+ * (`$1`) and a bare column (`$A`) are legitimate references, but a cell is where a value lives, and
+ * every caller that needs one was re-deriving that invariant by hand.
+ */
+export interface CellPosition {
+    readonly col: number;
+    readonly row: number;
+}
+/**
+ * Decode a reference that must name a single cell. Anchoring `$` signs are accepted and dropped.
+ *
+ * @throws {SyntaxError} if the reference is unparseable, or parses but omits an axis (`"A"`, `"1"`).
+ */
+export declare function decodeCellRef(reference: string): CellPosition;
+/**
+ * {@link decodeCellRef} for a reference that came out of a file rather than out of a caller:
+ * `undefined` for anything that does not name one cell, whether it is a range, a bare row or
+ * column, or outright garbage. A foreign producer writes all four, and none of them is worth
+ * throwing over when the reading code's answer is simply "then there is nothing here".
+ */
+export declare function tryDecodeCellRef(reference: string): CellPosition | undefined;
 /**
  * Decode a range reference (`A1:B2`, `$1:$1`, `Sheet1!$A:$A`) into its corners and
  * canonical dimensions. A single reference collapses to a degenerate range whose

package/dist/core/address.js

@@ -1,10 +1,23 @@
 export const MAX_COLUMN = 16384;
 export const MAX_ROW = 1048576;
+export function assertColumnInBounds(n) {
+    if (!Number.isInteger(n) || n < 1 || n > MAX_COLUMN) {
+        throw new RangeError(`column ${n} is out of bounds: Excel supports 1..${MAX_COLUMN}`);
+    }
+}
+export function assertRowInBounds(n) {
+    if (!Number.isInteger(n) || n < 1 || n > MAX_ROW) {
+        throw new RangeError(`row ${n} is out of bounds: Excel supports 1..${MAX_ROW}`);
+    }
+}
+export function rectsOverlap(a, b) {
+    return a.left <= b.right && b.left <= a.right && a.top <= b.bottom && b.top <= a.bottom;
+}
 const SINGLE_REF = /^\$?([A-Z]*)\$?(\d*)$/;
 const SHEET_PREFIX = /^(?:(?:'((?:[^']|'')*)')|([^'!]+))!(.*)$/;
 export function numberToColumn(n) {
     if (!Number.isInteger(n) || n < 1 || n > MAX_COLUMN) {
-        throw new RangeError(`column ${n} is out of bounds — Excel supports 1..${MAX_COLUMN}`);
+        throw new RangeError(`column ${n} is out of bounds: Excel supports 1..${MAX_COLUMN}`);
     }
     let letters = '';
     let remaining = n;
@@ -28,7 +41,7 @@ export function columnToNumber(letters) {
         n = n * 26 + (code - 64);
     }
     if (n > MAX_COLUMN) {
-        throw new RangeError(`column "${letters}" is out of bounds — Excel supports up to ${MAX_COLUMN} (XFD)`);
+        throw new RangeError(`column "${letters}" is out of bounds: Excel supports up to ${MAX_COLUMN} (XFD)`);
     }
     return n;
 }
@@ -53,6 +66,21 @@ export function decodeAddress(reference) {
     const row = digits.length > 0 ? Number.parseInt(digits, 10) : undefined;
     return { address: `${letters}${digits}`, col, row };
 }
+export function decodeCellRef(reference) {
+    const { col, row } = decodeAddress(reference);
+    if (col === undefined || row === undefined) {
+        throw new SyntaxError(`"${reference}" is not a single-cell reference: it omits a column or row`);
+    }
+    return { col, row };
+}
+export function tryDecodeCellRef(reference) {
+    try {
+        return decodeCellRef(reference);
+    }
+    catch {
+        return undefined;
+    }
+}
 export function decodeRange(reference) {
     const prefix = SHEET_PREFIX.exec(reference);
     let sheetName;
@@ -86,7 +114,7 @@ export function decodeRange(reference) {
 }
 export function encodeAddress(col, row) {
     if (!Number.isInteger(row) || row < 1) {
-        throw new RangeError(`row ${row} is out of bounds — rows start at 1`);
+        throw new RangeError(`row ${row} is out of bounds: rows start at 1`);
     }
     return `${numberToColumn(col)}${row}`;
 }

package/dist/core/autofilter.d.ts

@@ -18,7 +18,7 @@ export interface FilterColumn {
 /** The two criteria kinds this library models: a discrete value set, or operator predicates. */
 export type FilterCriteria = ValuesFilter | CustomFilter;
 /**
- * A column narrowed to a discrete set of allowed values — the checkbox list in Excel's dropdown.
+ * A column narrowed to a discrete set of allowed values: the checkbox list in Excel's dropdown.
  * A row survives when its cell in this column matches one of {@link values} (or is blank, when
  * {@link blank} is set).
  */
@@ -48,7 +48,7 @@ export declare function isCustomFilterOperator(value: string): value is CustomFi
  * Validate and normalise a settable autofilter into its canonical stored form. A bare range string
  * is the common case (dropdowns, no criteria); an {@link AutoFilter} object carries per-column
  * criteria too. Throws when the range is not a bounded rectangle, or a column's `colId` falls
- * outside it, or a custom filter does not carry one or two predicates — a filter authored wrong is
+ * outside it, or a custom filter does not carry one or two predicates: a filter authored wrong is
  * a bug to surface, not to silently repair. (The reader sanitises hostile input before it reaches
  * here, so load never trips these guards.)
  */

package/dist/core/cell.d.ts

@@ -3,8 +3,8 @@ import { type Alignment, type Border, type CellStyle, type Fill, type Font, type
 import { type CellValue, type RichTextRun, type ValueType } from './value.ts';
 import type { CellModel } from './worksheet.ts';
 /**
- * A single cell owns its value and every style facet outright. Each facet below — fill, number format,
- * font, border, alignment, protection, quote-prefix, and note — is held in the cell's own field and
+ * A single cell owns its value and every style facet outright. Each facet below (fill, number format,
+ * font, border, alignment, protection, quote-prefix, and note) is held in the cell's own field and
  * *replaced* (never mutated in place) by its setter, so a facet set on one cell never aliases or bleeds
  * onto its row, column, or sheet siblings. Each facet's own doc covers only what is specific to it.
  */
@@ -14,6 +14,7 @@ export declare class Cell {
     readonly row: number;
     /** 1-based column index. */
     readonly col: number;
+    /** @throws {RangeError} unless both axes are integers within Excel's grid. */
     constructor(row: number, col: number);
     /** Canonical A1 address of this cell (`"B3"`). */
     get address(): string;
@@ -23,12 +24,12 @@ export declare class Cell {
     /** The observable {@link ValueType} of the current value. */
     get type(): ValueType;
     /**
-     * The cell's value as plain text ({@link cellValueToText}), `""` when it is empty — so a reader
+     * The cell's value as plain text ({@link cellValueToText}), `""` when it is empty, so a reader
      * that only wants strings never has to narrow the value union itself.
      *
      * Read-only, because text is a *rendering* of the value and not a second place to store one:
      * writing `"3"` here could only mean the string `"3"`, which is exactly `value = '3'` and reads
-     * nothing like it. The number format is not applied either — the style is not the cell's value,
+     * nothing like it. The number format is not applied either: the style is not the cell's value,
      * so a currency cell's text carries no currency sign.
      */
     get text(): string;
@@ -39,27 +40,27 @@ export declare class Cell {
      *
      * This exists because a run's format element does **not** inherit anything. A `<rPr>` is a
      * *complete* character format, and any facet it omits falls back to the workbook default font
-     * ({@link Workbook.defaultFont}) — not to the cell's. Verified against Excel: a cell set to
+     * ({@link Workbook.defaultFont}), not to the cell's. Verified against Excel: a cell set to
      * Courier New 16 whose first run carries only `<b/>` renders that run in the workbook default face
      * at the default size, bold, while the rest of the cell renders Courier New 16. So a run authored
      * as `{bold: true}` beside a styled cell silently loses the face, which is the format's rule rather
-     * than a bug — and the reason this is a helper rather than a change to how runs are written.
+     * than a bug, and the reason this is a helper rather than a change to how runs are written.
      *
      * Composition is per facet: a facet the run names wins, one it omits comes from the cell. Assigning
      * `value` directly stays the bare path, for a caller who wants a run that deliberately falls back
      * to the workbook default.
      *
-     * A cell that names no font of its own needs no composition — an omitted facet already falls back
-     * to the workbook default, which is exactly what such a cell renders in — so the runs pass through
+     * A cell that names no font of its own needs no composition: an omitted facet already falls back
+     * to the workbook default, which is exactly what such a cell renders in, so the runs pass through
      * unchanged.
      */
     setRichText(runs: readonly RichTextRun[]): void;
     /**
-     * The cell's full style — fill, number format, font, border, alignment, and protection — as one
+     * The cell's full style (fill, number format, font, border, alignment, and protection) as one
      * {@link CellStyle}, for restyling a cell wholesale without importing {@link applyCellStyle}
      * separately (mirrors {@link Worksheet.model}'s getter/setter pair for the whole sheet). The
      * getter carries only the facets this cell has set (the same shape {@link cellToModel} emits);
-     * the setter lays each facet `style` carries onto this cell — like every per-facet setter, it
+     * the setter lays each facet `style` carries onto this cell and, like every per-facet setter, it
      * replaces that facet outright but leaves a facet `style` omits untouched, so `cell.style = {...}`
      * composes with prior per-facet sets rather than clearing them wholesale.
      */
@@ -71,35 +72,35 @@ export declare class Cell {
     /**
      * The cell's number-format code (`"0.00%"`, a custom accounting format, …), or
      * `undefined` for the General format. Stored verbatim: the invariant form Excel
-     * persists — `.` decimal, `,` grouping, `/` date separator — is neither localized
+     * persists (`.` decimal, `,` grouping, `/` date separator) is neither localized
      * nor rewritten, so the code round-trips character-for-character. A cell that also carries
      * a column-level format keeps both, so overriding one facet never drops the other.
      */
     get numFmt(): string | undefined;
     set numFmt(numFmt: string | undefined);
     /**
-     * The cell's font — bold/italic/underline, size, colour, typeface — as a partial set
+     * The cell's font (bold/italic/underline, size, colour, typeface) as a partial set
      * of the facets that differ from the default (only the facets actually set are carried,
      * exactly as OOXML stores them). `undefined` means the cell uses the workbook default font.
      */
     get font(): Font | undefined;
     set font(font: Font | undefined);
     /**
-     * The cell's border — the line style and colour of each side — or `undefined` when the
+     * The cell's border (the line style and colour of each side), or `undefined` when the
      * cell has none. An absent edge within a border means that side is unbordered, so reading
      * a cell never fabricates a border it does not have.
      */
     get border(): Border | undefined;
     set border(border: Border | undefined);
     /**
-     * The cell's alignment — how its content sits within the cell, plus the wrap/shrink flags —
+     * The cell's alignment (how its content sits within the cell, plus the wrap/shrink flags),
      * or `undefined` when it uses the defaults. The boolean flags are off unless explicitly set,
      * so a cell that never enabled wrapping never reads back wrapped.
      */
     get alignment(): Alignment | undefined;
     set alignment(alignment: Alignment | undefined);
     /**
-     * The cell's protection — its locked/hidden flags, enforced only once the sheet is protected —
+     * The cell's protection (its locked/hidden flags, enforced only once the sheet is protected),
      * or `undefined` when the cell carries neither. `locked` defaults to on in OOXML, so a cell
      * that never touched protection is implicitly locked and reads back as `undefined`, not as
      * `{locked: true}`; the flag only becomes explicit when a cell is unlocked.
@@ -110,7 +111,7 @@ export declare class Cell {
      * The quote-prefix flag: when set, a spreadsheet stores the cell's content as literal text even
      * when it looks like a formula or number, and shows a leading apostrophe in the formula bar without
      * that apostrophe being part of the stored value. `undefined` (or `false`) when unset. It is a
-     * cell-format flag — an attribute on the cell's `xf` record — so it composes independently of the
+     * cell-format flag, an attribute on the cell's `xf` record, so it composes independently of the
      * value.
      */
     get quotePrefix(): boolean | undefined;

package/dist/core/cell.js

@@ -1,4 +1,4 @@
-import { encodeAddress } from './address.js';
+import { assertColumnInBounds, assertRowInBounds, encodeAddress } from './address.js';
 import { NAMED_STYLE_ID } from './internal.js';
 import { assignStyleFacets, } from './style.js';
 import { cellValueToText, coerceCellValue, detectValueType, } from './value.js';
@@ -16,12 +16,8 @@ export class Cell {
     #namedStyleId;
     #note;
     constructor(row, col) {
-        if (!Number.isInteger(row) || row < 1) {
-            throw new RangeError(`cell row ${row} is out of bounds — rows start at 1`);
-        }
-        if (!Number.isInteger(col) || col < 1) {
-            throw new RangeError(`cell column ${col} is out of bounds — columns start at 1`);
-        }
+        assertRowInBounds(row);
+        assertColumnInBounds(col);
         this.row = row;
         this.col = col;
     }

package/dist/core/color-resolution.d.ts

@@ -1,21 +1,21 @@
 import type { Color } from './style.ts';
 import { type ThemeColorScheme } from './theme.ts';
 /**
- * The built-in indexed colour palette (ECMA-376 §18.8.27), by index. Entries 0–7 duplicate 8–15 —
+ * The built-in indexed colour palette (ECMA-376 §18.8.27), by index. Entries 0–7 duplicate 8–15, a
  * redundancy the spec preserves for backwards compatibility with the legacy formats this palette came
- * from — and the table is only 64 long: indices 64 and 65 are the *system* foreground and background,
+ * from, and the table is only 64 long: indices 64 and 65 are the *system* foreground and background,
  * which name whatever the operating system's window colours are and therefore have no fixed value at
  * all (see {@link SYSTEM_INDEXED_COLORS}).
  *
- * The spec writes each entry with a leading `00`. That byte is not an alpha channel — a palette of
- * fully transparent colours would be absurd — it is an artefact of the 32-bit colour records these
+ * The spec writes each entry with a leading `00`. That byte is not an alpha channel, since a palette
+ * of fully transparent colours would be absurd. It is an artefact of the 32-bit colour records these
  * values were lifted from, which is why {@link resolveColor} returns them fully opaque.
  */
 export declare const DEFAULT_INDEXED_COLORS: readonly string[];
 /**
  * The two indices that are not colours: 64 is the system foreground and 65 the system background.
  * They resolve to whatever the viewing system's window colours are, so this library reports them
- * unresolved rather than inventing black and white — a caller that wants to paint them must decide
+ * unresolved rather than inventing black and white: a caller that wants to paint them must decide
  * for itself what "automatic" means in its context. `indexed="64"` in particular is extremely common:
  * it is the placeholder every solid fill Excel writes carries as its background colour.
  */
@@ -27,14 +27,14 @@ export interface ColorResolutionContext {
     /**
      * The workbook's custom indexed palette, by index, each entry an ARGB string. Empty or absent means
      * the workbook rides {@link DEFAULT_INDEXED_COLORS}. A custom palette replaces the built-in one
-     * wholesale — that is what `<indexedColors>` means — so a short custom palette leaves the indices
+     * wholesale, which is what `<indexedColors>` means, so a short custom palette leaves the indices
      * past its end unresolved rather than falling through to the built-in entry.
      */
     readonly indexed?: readonly string[] | undefined;
 }
 /**
  * Resolve a colour reference to a concrete 8-hex ARGB string, or `undefined` when it cannot be
- * resolved — an `auto` colour, a system indexed colour, a theme slot the workbook's scheme does not
+ * resolved: an `auto` colour, a system indexed colour, a theme slot the workbook's scheme does not
  * declare, or an index past the end of a custom palette.
  *
  * Precedence follows what the encodings mean: an explicit `argb` is already concrete and wins; then

package/dist/core/column.d.ts

@@ -1,4 +1,5 @@
 import type { Cell } from './cell.ts';
+import { type AssertNever } from './internal.ts';
 import type { Alignment, Border, Fill, Font, Protection } from './style.ts';
 import type { CellValue } from './value.ts';
 import type { ColumnProperties, Worksheet } from './worksheet.ts';
@@ -6,12 +7,12 @@ export declare class Column {
     #private;
     /** 1-based column index. Fixed for this handle's lifetime. */
     readonly index: number;
-    /** @throws {RangeError} if the index is not a positive integer. */
+    /** @throws {RangeError} unless the index is an integer within Excel's column grid (1..16384). */
     constructor(sheet: Worksheet, index: number);
-    /** The column's letters (`"B"`) — the spreadsheet-facing name for {@link index}. */
+    /** The column's letters (`"B"`): the spreadsheet-facing name for {@link index}. */
     get letter(): string;
     /**
-     * The column's format record if it has one, else `undefined` — a read that never fabricates, so a
+     * The column's format record if it has one, else `undefined`: a read that never fabricates, so a
      * serializer can ask every column it visits whether there are attributes to emit without giving
      * each one an empty record. Read-only on purpose: {@link width} and its siblings are how a column
      * is formatted, and they create the record on first write.
@@ -19,12 +20,12 @@ export declare class Column {
     get properties(): Readonly<ColumnProperties> | undefined;
     /**
      * Stable key naming this column so a keyed-object row (see {@link Worksheet.addRow}) can place a
-     * value under it by name rather than position. In-memory only — never serialized to OOXML.
+     * value under it by name rather than position. In-memory only: never serialized to OOXML.
      */
     get key(): string | undefined;
     set key(key: string | undefined);
     /**
-     * Column width in character units — digits of the workbook default font's maximum digit width,
+     * Column width in character units: digits of the workbook default font's maximum digit width,
      * so what one unit measures moves with that font. `undefined` leaves the sheet default in force.
      *
      * Not bounded here, for the same reason {@link Row.height} is not, and for a stronger one:
@@ -79,17 +80,15 @@ export declare class Column {
      * cell holding `null`.
      *
      * Assigning places each value it names and leaves every other row untouched, mirroring
-     * {@link Row.values} — a hole or an explicit `undefined` skips that row, and a shorter array does
+     * {@link Row.values}: a hole or an explicit `undefined` skips that row, and a shorter array does
      * not clear the tail.
      */
     get values(): (CellValue | undefined)[];
     set values(values: (CellValue | undefined)[]);
 }
-type AssertNever<T extends never> = T;
 /**
- * Compile-time proof that {@link Column} mirrors every {@link ColumnProperties} field — including
+ * Compile-time proof that {@link Column} mirrors every {@link ColumnProperties} field, including
  * the six inherited `CellStyle` facets, so a seventh facet reaches this handle the moment it joins
  * the tuple. See the counterpart on `Row` for why the mirror needs proving rather than reviewing.
  */
 export type EveryColumnPropertyIsMirrored = AssertNever<Exclude<keyof ColumnProperties, keyof Column & keyof ColumnProperties>>;
-export {};

package/dist/core/column.js

@@ -1,12 +1,10 @@
-import { encodeAddress, numberToColumn } from './address.js';
+import { assertColumnInBounds, encodeAddress, numberToColumn } from './address.js';
 import { INTERNAL } from './internal.js';
 export class Column {
     #sheet;
     index;
     constructor(sheet, index) {
-        if (!Number.isInteger(index) || index < 1) {
-            throw new RangeError(`column ${index} is out of bounds — columns start at 1`);
-        }
+        assertColumnInBounds(index);
         this.#sheet = sheet;
         this.index = index;
     }

package/dist/core/comment-thread.d.ts

@@ -1,47 +1,56 @@
 /**
- * A registered identity a threaded comment can point at — an author, or someone `@mentioned` in a
+ * A registered identity a threaded comment can point at: an author, or someone `@mentioned` in a
  * message. One `<person>` of the workbook's `xl/persons/person.xml` registry.
  *
  * A single human legitimately has **several** entries: Excel registers a mentioned identity separately
  * from that person's authoring identity, with the same {@link displayName} and {@link userId} but a
- * different {@link id} and a different {@link providerId}. The id is therefore the only identity —
+ * different {@link id} and a different {@link providerId}. The id is therefore the only identity;
  * see {@link Workbook.getPerson}.
  */
 export interface Person {
     /** Brace-wrapped GUID this identity is referenced by. The only field that identifies it. */
     readonly id: string;
-    /** The name a spreadsheet app shows — not unique, and not an identity. */
+    /** The name a spreadsheet app shows. Not unique, and not an identity. */
     readonly displayName: string;
     /** Identity-provider handle, `S::<email>::<tenant-guid>` for an AzureAD account. */
     readonly userId?: string;
-    /** The provider that registered this entry — `AD` for a directory account, `PeoplePicker` for an
+    /** The provider that registered this entry: `AD` for a directory account, `PeoplePicker` for an
      * identity interned by being mentioned. */
     readonly providerId?: string;
 }
 /**
- * An `@mention` inside a message: who was named, and the run of {@link Comment.text} that renders as the
- * mention chip.
+ * An `@mention` as the file spells it: who was named, and the run of {@link Comment.text} that
+ * renders as the mention chip.
  *
- * The offsets are only meaningful against that exact text — shift either and a spreadsheet app
+ * The offsets are only meaningful against that exact text: shift either and a spreadsheet app
  * highlights the wrong words.
+ *
+ * This is the wire shape, shared with the codec that reads it. {@link Mention} is this plus the
+ * identity we resolved the id to, which is the one thing the file does not carry.
  */
-export interface Mention {
-    /**
-     * The mentioned identity, resolved through the workbook registry. Absent when the file names an id
-     * the registry does not hold (a mention left dangling by a foreign generator); {@link personId}
-     * still says who was meant.
-     */
-    readonly person?: Person;
+export interface MentionRef {
     /** The mentioned {@link Person.id} exactly as written, so a dangling mention stays diagnosable. */
     readonly personId: string;
     /** Excel's own id for this mention, preserved so re-emitting it does not invent a new one. */
     readonly mentionId?: string;
-    /** 0-based character offset into {@link Comment.text} where the mention starts. */
+    /**
+     * 0-based character offset into {@link Comment.text} where the mention starts. Verified against
+     * desktop Excel by rendering: the chip covers exactly `[startIndex, startIndex + length)`.
+     */
     readonly startIndex: number;
     /** Length of the mention in characters, **counting the leading `@`** (`@Grace Hopper` is 13). */
     readonly length: number;
 }
-/** One message of a {@link CommentThread} — what a single person wrote, once. */
+/** A {@link MentionRef} with its identity resolved against the workbook's person registry. */
+export interface Mention extends MentionRef {
+    /**
+     * The mentioned identity, resolved through the workbook registry. Absent when the file names an id
+     * the registry does not hold (a mention left dangling by a foreign generator); {@link personId}
+     * still says who was meant.
+     */
+    readonly person?: Person;
+}
+/** One message of a {@link CommentThread}: what a single person wrote, once. */
 export interface Comment {
     /** Brace-wrapped GUID identifying this message, preserved verbatim from the file. */
     readonly id: string;
@@ -54,7 +63,7 @@ export interface Comment {
     readonly personId?: string;
     /**
      * When it was written, verbatim. Excel writes local wall-clock with fractional seconds and no
-     * timezone (`2026-07-24T10:56:41.72`), which is not a round-trippable instant — keeping the string
+     * timezone (`2026-07-24T10:56:41.72`), which is not a round-trippable instant. Keeping the string
      * spares the reader from inventing a zone the file never stated.
      */
     readonly date?: string;
@@ -67,7 +76,7 @@ export interface Comment {
  * The one spelling every threaded-comment identifier must take on the wire: brace-wrapped, upper-case hex.
  *
  * Verified against the OOXML schema, which pins `person/@id`, a message's `id`/`personId`/`parentId`, and a
- * mention's `mentionpersonId`/`mentionId` to exactly `\{[0-9A-F]{8}-…\}` — a bare GUID and a lower-case one
+ * mention's `mentionpersonId`/`mentionId` to exactly `\{[0-9A-F]{8}-…\}`, so a bare GUID and a lower-case one
  * are each rejected outright. So this normalises rather than merely checking: a caller passing
  * `crypto.randomUUID()` gets a valid file instead of one Excel offers to repair.
  *
@@ -82,7 +91,7 @@ export declare function commentThreadGuid(value: string, what: string): string;
  * `startIndex` and `length` are `xsd:unsignedInt`, so `4294967295` validates and `4294967296` is rejected
  * as "not a valid 'UInt32' value".
  *
- * Wildly beyond any real message, and that is the point — the ceiling exists so a value from a hostile
+ * Wildly beyond any real message, and that is the point: the ceiling exists so a value from a hostile
  * part can never reach the serialiser. JavaScript spells a large enough number in exponent form
  * (`String(1e21)` is `"1e+21"`), which is not a numeric literal any schema accepts, and one invalid
  * attribute is enough for Excel to offer to repair the whole conversation away.
@@ -91,8 +100,8 @@ export declare const MENTION_OFFSET_MAX = 4294967295;
 /**
  * A mention offset as the wire accepts it: a whole number within {@link MENTION_OFFSET_MAX}.
  *
- * The authoring path alone throws. A file's own mentions are read leniently — one carrying an unusable
- * offset is dropped, keeping the message text and losing only the chip — because a foreign generator's
+ * The authoring path alone throws. A file's own mentions are read leniently: one carrying an unusable
+ * offset is dropped, keeping the message text and losing only the chip, because a foreign generator's
  * arithmetic is not something a caller can fix, whereas their own is.
  *
  * @throws {SyntaxError} if the value is negative, fractional, or beyond the wire's ceiling.
@@ -101,8 +110,8 @@ export declare function commentThreadOffset(value: number, what: string): number
 /** A conversation anchored to one cell: what was asked, every reply, and whether it was resolved. */
 export interface CommentThread {
     /**
-     * A1 reference of the single cell the conversation hangs off, canonicalised — no `$` anchors, always
-     * a column and a row — so two anchors compare as plain strings and a writer can resolve it without
+     * A1 reference of the single cell the conversation hangs off, canonicalised with no `$` anchors and
+     * always a column and a row, so two anchors compare as plain strings and a writer can resolve it without
      * re-validating it.
      */
     readonly ref: string;

package/dist/core/comment-thread.js

@@ -2,16 +2,16 @@ const GUID = /^\{?([0-9a-f]{8})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a
 export function commentThreadGuid(value, what) {
     const match = GUID.exec(value.trim());
     if (match === null) {
-        throw new SyntaxError(`${what} must be a GUID — Excel writes threaded-comment ids as ` +
-            `"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}" — but got "${value}"`);
+        throw new SyntaxError(`${what} must be a GUID: Excel writes threaded-comment ids as ` +
+            `"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}", but got "${value}"`);
     }
     return `{${match.slice(1).join('-').toUpperCase()}}`;
 }
 export const MENTION_OFFSET_MAX = 0xffff_ffff;
 export function commentThreadOffset(value, what) {
     if (!Number.isInteger(value) || value < 0 || value > MENTION_OFFSET_MAX) {
-        throw new SyntaxError(`${what} must be a whole number between 0 and ${MENTION_OFFSET_MAX} — a mention's span is ` +
-            `written as an unsigned 32-bit integer — but got ${value}`);
+        throw new SyntaxError(`${what} must be a whole number between 0 and ${MENTION_OFFSET_MAX}: a mention's span is ` +
+            `written as an unsigned 32-bit integer, but got ${value}`);
     }
     return value;
 }

package/dist/core/conditional-formatting-overlay.d.ts

@@ -2,7 +2,7 @@ import { type ConditionalFormatting } from './conditional-formatting.ts';
 export declare class ConditionalFormattingOverlay {
     #private;
     /**
-     * Attach a conditional formatting to a target range. `formatting.ref` is an OOXML `sqref` — one
+     * Attach a conditional formatting to a target range. `formatting.ref` is an OOXML `sqref`: one
      * range (`"A1:A10"`), a whole column, or several space-separated areas (`"A1:C1 A3:C3"`) sharing one
      * rule set. The block is stored once against the range, defensively copied so the getter never hands
      * back a reference into the caller's object.

package/dist/core/conditional-formatting.d.ts

@@ -1,6 +1,6 @@
 import type { Color, DifferentialStyle } from './style.ts';
 /**
- * One anchor of a colour-scale, data-bar, or icon-set scale — a "conditional format value object".
+ * One anchor of a colour-scale, data-bar, or icon-set scale: a "conditional format value object".
  * `type` names how `value` is read: a literal `num`, a `percent`/`percentile` of the range, a
  * `formula`, or the range's own `min`/`max` (which carry no value).
  */
@@ -15,7 +15,7 @@ export interface CfValueObject {
  */
 export interface ConditionalFormattingRule {
     type: string;
-    /** Evaluation precedence; lower wins. Excel requires one — the writer supplies it when absent. */
+    /** Evaluation precedence; lower wins. Excel requires one, so the writer supplies it when absent. */
     priority?: number;
     /** Halt evaluation of lower-priority rules on any cell this rule matches. */
     stopIfTrue?: boolean;
@@ -58,7 +58,7 @@ export interface ConditionalFormattingRule {
     /** timePeriod window (`today`, `lastWeek`, …). */
     timePeriod?: string;
 }
-/** A set of rules bound to the range(s) they cover. `ref` is an OOXML `sqref` — one or more
+/** A set of rules bound to the range(s) they cover. `ref` is an OOXML `sqref`: one or more
  * space-separated areas (`"A1:C1 A3:C3 A5:C5"`), the shape Excel writes when one rule is applied to
  * several non-contiguous selections at once. */
 export interface ConditionalFormatting {

package/dist/core/data-validation-overlay.d.ts

@@ -8,7 +8,7 @@ export declare class DataValidationOverlay {
      * through {@link at}.
      *
      * Pass `{extended: true}` to mark a rule that belongs in the 2009 extension form
-     * (`<x14:dataValidation>`) — the carrier Excel uses for a list source on another sheet and other
+     * (`<x14:dataValidation>`), the carrier Excel uses for a list source on another sheet and other
      * shapes the standard element cannot express. The reader sets it for a rule found in that form so a
      * round-trip writes it back there instead of silently corrupting the cross-sheet reference.
      */

package/dist/core/data-validation.d.ts

@@ -6,7 +6,7 @@ export type DataValidationType = 'list' | 'whole' | 'decimal' | 'date' | 'time'
 export type DataValidationOperator = 'between' | 'notBetween' | 'equal' | 'notEqual' | 'greaterThan' | 'lessThan' | 'greaterThanOrEqual' | 'lessThanOrEqual';
 /** How Excel reacts to input that fails the rule. */
 export type DataValidationErrorStyle = 'stop' | 'warning' | 'information';
-/** One validation rule. `formulae` holds the operand(s) — `formula1` then optional `formula2`: a
+/** One validation rule. `formulae` holds the operand(s), `formula1` then optional `formula2`: a
  * numeric literal is stored as a number, while a cell reference, defined name, or list source keeps
  * its verbatim string. */
 export interface DataValidation {
@@ -22,9 +22,9 @@ export interface DataValidation {
     prompt?: string;
     promptTitle?: string;
 }
-/** A validation bound to the range(s) it covers. `sqref` is an OOXML `sqref` — one or more
+/** A validation bound to the range(s) it covers. `sqref` is an OOXML `sqref`: one or more
  * space-separated ranges. `extended` marks a rule stored in the 2009 extension form
- * (`<x14:dataValidation>` inside the worksheet `<extLst>`) — Excel's carrier for validations a
+ * (`<x14:dataValidation>` inside the worksheet `<extLst>`), Excel's carrier for validations a
  * legacy `<dataValidation>` cannot express, such as a list source on another sheet. The flag is how
  * a rule read from that form remembers to be written back to it, rather than downgraded to the
  * standard element (which would corrupt a cross-sheet reference). */