@shbernal/ts-xlsx 1.3.1 → 2.1.0

package/dist/core/worksheet.d.ts

@@ -1,10 +1,10 @@
 import { type AutoFilter } from './autofilter.ts';
 import { Cell } from './cell.ts';
 import { Column } from './column.ts';
-import { type CommentThread } from './comment-thread.ts';
+import type { CommentThread } from './comment-thread.ts';
 import type { ConditionalFormatting } from './conditional-formatting.ts';
 import type { DataValidation, DataValidationEntry } from './data-validation.ts';
-import { type AnchoredImage, type AnchorPoint, type ImageAnchor, type ImageEditAs } from './image.ts';
+import type { AnchoredImage, AnchorPoint, ImageAnchor, ImageEditAs } from './image.ts';
 import { INTERNAL } from './internal.ts';
 import type { HeaderFooter, PageBreak, PageMargins, PageSetup, PrintOptions } from './page-setup.ts';
 import { type ParsedPivotTable, PivotTable, type PivotTableOptions } from './pivot-table.ts';
@@ -15,9 +15,19 @@ import { Row } from './row.ts';
 import type { CellStyle, Color, Fill } from './style.ts';
 import { Table, type TableOptions } from './table.ts';
 import type { CellValue } from './value.ts';
+/**
+ * Whether a thing Excel can hide is showing: a sheet's tab, or the document window itself.
+ *
+ * One type for two schema enumerations. `ST_SheetState` and `ST_Visibility` are declared separately
+ * in ECMA-376 and carry the same three tokens with the same meanings, and `veryHidden` means the same
+ * thing in both: hidden, and not offered in the unhide list.
+ */
+export type Visibility = 'visible' | 'hidden' | 'veryHidden';
+/** Narrow a raw `<sheet state>` or `<workbookView visibility>` token to a known {@link Visibility}. */
+export declare function isVisibility(value: string): value is Visibility;
 export interface WorksheetState {
     /** Sheet visibility, as Excel models it. Defaults to `visible`. */
-    readonly state: 'visible' | 'hidden' | 'veryHidden';
+    readonly state: Visibility;
 }
 /** Format defaults applied to every row/column that carries no explicit override. */
 export interface WorksheetProperties {
@@ -39,7 +49,7 @@ export interface OutlineProperties {
 /**
  * A worksheet's frozen-pane view. `state` `'frozen'` locks the top `ySplit` rows and left `xSplit`
  * columns in place while the rest scrolls; `'normal'` (the default) has no split and emits no
- * `<pane>` — writing a normal view leaves no leftover pane markup that would trip Excel's repair
+ * `<pane>`: writing a normal view leaves no leftover pane markup that would trip Excel's repair
  * prompt. An empty object is a normal view.
  */
 export interface SheetView {
@@ -64,12 +74,12 @@ export interface SheetView {
 /**
  * Per-column formatting. A column may exist purely to carry these, with no cells. The style
  * facets are *defaults* for the column's cells: a cell that sets a facet of its own wins, but
- * one that leaves a facet unset inherits the column's — the same precedence Excel applies, and
+ * one that leaves a facet unset inherits the column's, the same precedence Excel applies, and
  * symmetric with how a {@link RowProperties} fill defaults a row's cells.
  */
 export interface ColumnProperties extends CellStyle {
     /** Stable key naming the column so a keyed-object row (see {@link Worksheet.addRow}) can place a
-     * value under it by name rather than position. In-memory only — it is not serialized to OOXML. */
+     * value under it by name rather than position. In-memory only: it is not serialized to OOXML. */
     key?: string;
     /** Column width in character units. */
     width?: number;
@@ -105,26 +115,34 @@ export interface CellModel extends CellStyle {
     note?: string | undefined;
 }
 /**
- * A serialisable snapshot of a worksheet's value and overlay content — its cells and their styles,
- * the column/row/page metadata, and the sheet-level overlays (merges, data validations, conditional
- * formattings, tables, the autofilter, protection). {@link Worksheet.model} exports one; assigning
- * it back reproduces that content. The getter and setter cover exactly the same fields, so a
- * `dst.model = src.model` round-trip drops none of it — an export field the import ignored would
- * silently lose data, the historical merge-loss failure this contract exists to prevent. Both
- * directions are driven from one field table (`core/worksheet-model.ts`), which the compiler proves
- * covers every field below, so adding a field here without wiring it fails the build.
+ * A serialisable snapshot of a worksheet's value and overlay content: its cells and their styles,
+ * the column/row/page metadata, the frozen-pane view, and the sheet-level overlays (merges, data
+ * validations, conditional formattings, tables, the autofilter, protection). {@link Worksheet.model}
+ * exports one; assigning it back reproduces that content. The getter and setter cover exactly the
+ * same fields, so a `dst.model = src.model` round-trip drops none of it: an export field the import
+ * ignored would silently lose data, the historical merge-loss failure this contract exists to
+ * prevent. Both directions are driven from one field table (`core/worksheet-model.ts`), which the
+ * compiler proves covers every field below, so adding a field here without wiring it fails the build.
+ *
+ * The line between what belongs here and what does not is **workbook-independence**: a field earns
+ * its place when its value means the same thing on any sheet of any workbook. That is the test a new
+ * field is measured against, and applying it is what admitted the autofilter and the frozen-pane view
+ * after each had been omitted for no stated reason (ADR-0005 §2).
  *
- * Out of scope by design: content that carries workbook-level identity rather than pure sheet
- * state — anchored and background images (their bytes live on the {@link Workbook}), pivot tables
- * (their source references a live worksheet), and byte-preserved parts (charts, vector drawings,
- * slicers) kept verbatim for round-tripping. These stay with their source sheet; a model assignment
- * neither copies nor clears them.
+ * Out of scope by design: content carrying workbook-level identity rather than pure sheet state.
+ * That covers anchored and background images (their bytes live on the {@link Workbook}), pivot tables
+ * (their source references a live worksheet), threaded comments (their authors are ids into the
+ * workbook's {@link Workbook.persons} registry, so a copied conversation would name an author the
+ * destination has never heard of), and byte-preserved parts (charts, vector drawings, slicers) kept
+ * verbatim for round-tripping. These stay with their source sheet; a model assignment neither copies
+ * nor clears them.
  */
 export interface WorksheetModel {
     state: WorksheetState['state'];
     tabColor: Color | undefined;
     properties: WorksheetProperties;
     outline: OutlineProperties;
+    view: SheetView;
     pageSetup: PageSetup;
     printOptions: PrintOptions;
     pageMargins: PageMargins;
@@ -163,7 +181,7 @@ export declare class Worksheet {
     readonly properties: WorksheetProperties;
     /**
      * Outline summary-position flags. Mutate in place: `sheet.outline.summaryBelow = false`. Empty
-     * means unset — the writer emits no `<outlinePr>` and a round-trip never fabricates one.
+     * means unset: the writer emits no `<outlinePr>` and a round-trip never fabricates one.
      */
     readonly outline: OutlineProperties;
     /**
@@ -173,13 +191,13 @@ export declare class Worksheet {
     readonly view: SheetView;
     /**
      * Print-scaling and orientation. Mutate in place: `sheet.pageSetup.fitToPage = true`. Empty means
-     * unset — the writer emits neither `<pageSetUpPr>` nor `<pageSetup>` and a round-trip never
+     * unset: the writer emits neither `<pageSetUpPr>` nor `<pageSetup>` and a round-trip never
      * fabricates them.
      */
     readonly pageSetup: PageSetup;
     /**
      * Print-toggle flags (`<printOptions>`): centring, and whether headings/gridlines print. Mutate in
-     * place: `sheet.printOptions.gridLines = true`. Empty means unset — the writer emits no element and
+     * place: `sheet.printOptions.gridLines = true`. Empty means unset. The writer emits no element and
      * a round-trip never fabricates one.
      */
     readonly printOptions: PrintOptions;
@@ -217,8 +235,8 @@ export declare class Worksheet {
     /** Whether a cell has been materialised at the given 1-based position. */
     hasCell(row: number, col: number): boolean;
     /**
-     * A handle on a 1-based column: its formatting, its cells, and its values. Cheap and stateless —
-     * it creates neither cells nor a format record, so asking about a column costs nothing and does
+     * A handle on a 1-based column: its formatting, its cells, and its values. Cheap and stateless.
+     * It creates neither cells nor a format record, so asking about a column costs nothing and does
      * not extend the used range. Writing through it (`getColumn(2).width = 12`) is what materialises
      * the record.
      *
@@ -226,7 +244,7 @@ export declare class Worksheet {
      */
     getColumn(index: number): Column;
     /**
-     * A handle on a 1-based row: its formatting, its cells, and its values. Cheap and stateless — it
+     * A handle on a 1-based row: its formatting, its cells, and its values. Cheap and stateless. It
      * creates neither cells nor a format record, so asking about a row costs nothing and does not
      * extend the used range. Writing through it (`getRow(3).height = 20`) is what materialises the
      * record.
@@ -235,7 +253,7 @@ export declare class Worksheet {
      */
     getRow(number: number): Row;
     /**
-     * A handle on a rectangular block of cells — `getRange('B2:D5')`, or the same block by its
+     * A handle on a rectangular block of cells: `getRange('B2:D5')`, or the same block by its
      * inclusive corners as `getRange(2, 2, 5, 4)`. Cheap and stateless like {@link getRow} and
      * {@link getColumn}: it creates no cells and does not extend the used range.
      *
@@ -254,7 +272,7 @@ export declare class Worksheet {
     getRange(reference: string): Range;
     getRange(top: number, left: number, bottom: number, right: number): Range;
     /**
-     * The 1-based index of the last row carrying anything — data or its own formatting —
+     * The 1-based index of the last row carrying anything (data or its own formatting),
      * or 0 for an empty sheet. Spans gaps: a value in row 5 makes this 5 even if rows 2–4
      * are empty. This is the used-range extent, not a populated-row tally (see
      * {@link actualRowCount}).
@@ -263,29 +281,29 @@ export declare class Worksheet {
     /** The number of rows that hold at least one non-empty cell, ignoring gaps and formatting-only rows. */
     get actualRowCount(): number;
     /**
-     * The 1-based index of the last column carrying anything — a non-empty cell or its own format
-     * properties — or 0 for an empty sheet. The used-range width, mirroring {@link rowCount} for the
+     * The 1-based index of the last column carrying anything (a non-empty cell or its own format
+     * properties), or 0 for an empty sheet. The used-range width, mirroring {@link rowCount} for the
      * other axis: a value in column E makes this 5 even if columns B–D are empty.
      */
     get columnCount(): number;
     /**
-     * The sheet's used range as one handle — `A1` through the last row and column that carry
-     * anything — or `undefined` when there is no rectangle to name.
+     * The sheet's used range as one handle: `A1` through the last row and column that carry
+     * anything, or `undefined` when there is no rectangle to name.
      *
      * This is {@link rowCount} and {@link columnCount} said once, so a caller stops reassembling
      * `A1:${numberToColumn(sheet.columnCount)}${sheet.rowCount}` by hand. That is what an
-     * {@link autoFilter} covering the whole sheet wants — `sheet.autoFilter = sheet.usedRange.address`
-     * — and Excel writes exactly that ref for a filter it applies itself. A header-only ref filters
+     * {@link autoFilter} covering the whole sheet wants (`sheet.autoFilter = sheet.usedRange.address`),
+     * and Excel writes exactly that ref for a filter it applies itself. A header-only ref filters
      * nothing, which is the bug this exists to make hard to write.
      *
      * It inherits both counts' definition of *used*, so it spans gaps (a value in `E5` and nothing
-     * else still gives `A1:E5`) and includes a line carrying only its own formatting — a set column
+     * else still gives `A1:E5`) and includes a line carrying only its own formatting: a set column
      * width, an outline level, a merge reaching past the last value. `undefined` therefore means
      * strictly "no rectangle": an empty sheet, or one carrying only row formatting and no columns at
      * all (or the reverse), where an axis has no extent to bound the other against.
      *
-     * Not the same thing as the `<dimension>` a written package records. That is the *tight* box —
-     * top-left at the first used cell, formatting-only rows excluded — because Excel writes it to
+     * Not the same thing as the `<dimension>` a written package records. That is the *tight* box,
+     * top-left at the first used cell and formatting-only rows excluded, because Excel writes it to
      * describe where the data is, not what the grid spans. This handle is anchored at `A1`, because
      * a caller asking for the used range means the block to read, style or filter.
      */
@@ -312,7 +330,7 @@ export declare class Worksheet {
     /** The tables defined on this sheet, in definition order. */
     get tables(): readonly Table[];
     /** The table with the given name (case-sensitive, the identifier Excel uses), or `undefined`.
-     * A table read back from a file is fully hydrated — its rows can be read and appended to. */
+     * A table read back from a file is fully hydrated: its rows can be read and appended to. */
     getTable(name: string): Table | undefined;
     /**
      * Add a pivot table to this (destination) sheet, summarising a source sheet's data. The source is
@@ -325,7 +343,7 @@ export declare class Worksheet {
     /** The pivot tables hosted on this sheet, in definition order. */
     get pivotTables(): readonly PivotTable[];
     /**
-     * Pivot tables reconstructed from a loaded package, in the order the reader found them — a
+     * Pivot tables reconstructed from a loaded package, in the order the reader found them: a
      * read-only inspection view (source range, field roles, value field, aggregation). A pivot
      * authored on this sheet via {@link addPivotTable} does not appear here; a pivot loaded from a
      * file does not appear in {@link pivotTables}. The loaded pivots re-emit verbatim through
@@ -333,13 +351,13 @@ export declare class Worksheet {
      */
     get loadedPivotTables(): readonly ParsedPivotTable[];
     /**
-     * Anchor a threaded conversation to a cell — Excel's modern review comment: an opening message, its
-     * replies, and whether the discussion was marked resolved. Distinct from a cell's legacy note
-     * ({@link Cell.note}), and mutually exclusive with one: Excel refuses to put both on one cell, and a
-     * cell carrying both is written back as the conversation alone.
+     * Anchor a threaded conversation to a cell. This is Excel's modern review comment: an opening
+     * message, its replies, and whether the discussion was marked resolved. Distinct from a cell's
+     * legacy note ({@link Cell.note}), and mutually exclusive with one: Excel refuses to put both on
+     * one cell, and a cell carrying both is written back as the conversation alone.
      *
      * Every message supplies its own {@link Comment.id} and {@link Comment.date}, and names its author by
-     * {@link Comment.personId} into the workbook registry ({@link Workbook.addPerson}) — the writer has no
+     * {@link Comment.personId} into the workbook registry ({@link Workbook.addPerson}): the writer has no
      * clock and no id generator, so nothing here is invented and the same workbook always serialises to the
      * same bytes. Every id is normalised to the brace-wrapped upper-case GUID form the format requires, so a
      * `crypto.randomUUID()` is accepted as-is.
@@ -347,7 +365,7 @@ export declare class Worksheet {
      * Message ids must be unique **within this sheet**, because that is the scope in which they mean
      * anything: a reply names its thread by the head's id inside the sheet's own part, and the legacy
      * fallback comment binds its cell by the same id inside the sheet's own comments part. Two sheets reusing
-     * one id is therefore harmless and is not rejected — Excel's ids happen to be globally unique, but
+     * one id is therefore harmless and is not rejected: Excel's ids happen to be globally unique, but
      * nothing resolves across a part boundary.
      *
      * @throws {SyntaxError} if the anchor does not resolve to a single cell, if any id is not a GUID, if a
@@ -356,7 +374,7 @@ export declare class Worksheet {
      */
     addCommentThread(thread: CommentThread): void;
     /**
-     * The threaded conversations on this sheet — Excel's modern review comments (author, timestamp,
+     * The threaded conversations on this sheet: Excel's modern review comments (author, timestamp,
      * replies, resolved state, `@mentions`). Empty for a sheet with none. Distinct from a cell's legacy note
      * ({@link Cell.note}).
      */
@@ -399,7 +417,7 @@ export declare class Worksheet {
      */
     addImageAnchor(imageId: number, anchor: ImageAnchor): void;
     /** Drop every anchor of the given workbook image from this sheet. The image stays registered on the
-     * workbook — another sheet may still show it — so only this sheet's anchors are removed; the writer
+     * workbook (another sheet may still show it), so only this sheet's anchors are removed; the writer
      * then omits any media no sheet anchors any longer. */
     removeImage(imageId: number): void;
     /** The images anchored to this sheet, in the order they were added. */
@@ -416,11 +434,11 @@ export declare class Worksheet {
     get preservedReferences(): readonly PreservedWorksheetReference[];
     /**
      * Merge a range of cells (`"A1:B2"`). A range that overlaps an already-merged region is
-     * rejected — Excel forbids overlapping merges and writes such geometry as a corrupt file.
+     * rejected: Excel forbids overlapping merges and writes such geometry as a corrupt file.
      * Whole-row/column ranges (`"A:A"`) are unbounded, carry no rectangle, and are not overlap-checked.
      *
      * Any value already sitting in a covered non-anchor cell is discarded, keeping only the top-left
-     * anchor's — exactly how Excel collapses a range on merge. Leaving it would emit a populated `<c>`
+     * anchor's, exactly how Excel collapses a range on merge. Leaving it would emit a populated `<c>`
      * under the `<mergeCell>` ref, the geometry Excel opens with a repair prompt. Covered-cell styles
      * survive (a border spanning the merge is legal), so only the conflicting value is cleared.
      */
@@ -428,15 +446,15 @@ export declare class Worksheet {
     /** The merged ranges on this sheet, in the order they were added. */
     get merges(): readonly string[];
     /**
-     * The sheet's autofilter — its range plus any per-column criteria — or `undefined` when the sheet
+     * The sheet's autofilter (its range plus any per-column criteria), or `undefined` when the sheet
      * carries none. Setting one turns on the header-row filter dropdowns Excel draws over the range;
      * the writer emits both the sheet's `<autoFilter>` element and the hidden `_FilterDatabase` defined
      * name Excel derives from it. Setting `undefined` clears the filter.
      *
-     * A bare range string is the ergonomic common case — `sheet.autoFilter = 'A1:C10'` for dropdowns
+     * A bare range string is the ergonomic common case: `sheet.autoFilter = 'A1:C10'` for dropdowns
      * with no active criteria; pass an {@link AutoFilter} object to narrow columns. Either way the
      * value is normalised on assignment (range to canonical `A1:C10` form) and the getter returns the
-     * structured object. The range must be a bounded rectangle — a whole-row/column reference is not a
+     * structured object. The range must be a bounded rectangle: a whole-row/column reference is not a
      * filterable region and is rejected.
      */
     get autoFilter(): AutoFilter | undefined;
@@ -454,7 +472,7 @@ export declare class Worksheet {
      * the rule through {@link dataValidationAt}.
      *
      * 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.
      */
@@ -464,7 +482,7 @@ export declare class Worksheet {
     /** The data validations on this sheet, each bound to its target range, in insertion order. */
     get dataValidations(): readonly DataValidationEntry[];
     /**
-     * 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.
@@ -481,8 +499,8 @@ export declare class Worksheet {
      * Remove `count` rows starting at the 1-based `start`, then insert the given rows in their place.
      * Rows below the edit shift by `inserts.length - count`: a delete pulls the tail up, an insert
      * pushes it down, and doing both at once is a replace. Each inserted row takes either
-     * {@link RowInput} shape — a positional array from column A, or a key-addressed object — exactly
-     * like {@link addRow}. A `count` larger than the rows present simply clears the tail — it never
+     * {@link RowInput} shape, a positional array from column A or a key-addressed object, exactly
+     * like {@link addRow}. A `count` larger than the rows present simply clears the tail; it never
      * silently becomes a no-op. Cells carry their full style to the shifted position, and merged ranges
      * shift with the rows they cover.
      *
@@ -500,19 +518,19 @@ export declare class Worksheet {
     /**
      * Append a row of `values` after the last used row, returning the cells it materialised.
      * The append point is {@link rowCount}` + 1`, so the row lands below every row that holds
-     * data or its own formatting — never overwriting existing content, unlike {@link insertRow},
+     * data or its own formatting, never overwriting existing content, unlike {@link insertRow},
      * which shifts and needs a position. Unlike {@link spliceRows}, appending shifts nothing, so
      * it never disturbs merges or the rows above.
      *
-     * A row takes either shape: a positional array whose values map to columns from A — a hole in a
-     * sparse array (`['a', , 'c']`) leaves that column untouched — or a keyed object whose values
-     * land under the columns carrying the matching {@link ColumnProperties.key}.
+     * A row takes either shape. A positional array maps its values to columns from A, and a hole in a
+     * sparse array (`['a', , 'c']`) leaves that column untouched. A keyed object lands its values
+     * under the columns carrying the matching {@link ColumnProperties.key}.
      */
     addRow(values: RowInput): Cell[];
     /**
      * Append several rows after the last used row in one call, returning the cells materialised
-     * for each. The rows stack in order — the first lands at {@link rowCount}` + 1`, the next
-     * directly below it — so a later row never collides with an earlier one even when both are
+     * for each. The rows stack in order: the first lands at {@link rowCount}` + 1`, the next
+     * directly below it, so a later row never collides with an earlier one even when both are
      * value-less. Each row is an array or a keyed object independently, so a mixed batch is fine.
      * The bulk form of {@link addRow}.
      */
@@ -529,8 +547,8 @@ export declare class Worksheet {
     unfreeze(): void;
     /**
      * Copy the row at the 1-based `start`, `options.count` times (default 1). With `options.insert`
-     * (the default) the copies are inserted directly after the source, shifting the rows below — and
-     * any merged range there — down by `count`; otherwise the copies overwrite the rows immediately
+     * (the default) the copies are inserted directly after the source, shifting the rows below, and
+     * any merged range there, down by `count`; otherwise the copies overwrite the rows immediately
      * below without shifting. Each copy is a faithful duplicate of the source's values and per-cell
      * styles, and carries no merge of its own, so a range can be merged onto a duplicated row afterwards.
      *
@@ -542,7 +560,7 @@ export declare class Worksheet {
     }): void;
     /**
      * Remove `count` columns starting at the 1-based `start`, then insert the given columns in their
-     * place — the column analog of {@link spliceRows}. Columns to the right shift by
+     * place: the column analog of {@link spliceRows}. Columns to the right shift by
      * `inserts.length - count`, keeping their values and styles, and a merged range lying wholly to
      * the right of the edit re-anchors to its new columns. Each inserted column is an array of values
      * indexed by row (index 0 → row 1); an empty array inserts a blank column.
@@ -561,29 +579,32 @@ export declare class Worksheet {
     /**
      * Append a column of `values` after the last used column, returning the cells it materialised.
      * The append point is {@link columnCount}` + 1`, so the column lands right of every column that
-     * holds data or its own formatting — never overwriting existing content, unlike {@link insertColumn},
+     * holds data or its own formatting, never overwriting existing content, unlike {@link insertColumn},
      * which shifts and needs a position. Unlike {@link spliceColumns}, appending shifts nothing, so it
      * never disturbs merges or the columns to its left.
      *
      * `values` is an array indexed by row (index 0 → row 1); a hole or an explicit `undefined` leaves
-     * that row untouched, mirroring {@link addRow}'s positional-array shape.
+     * that row untouched, mirroring {@link addRow}'s positional-array shape. That is the only shape a
+     * column takes: the other {@link RowInput} form addresses columns by their
+     * {@link ColumnProperties.key}, and a column's values are indexed by *row*, which carries no key,
+     * so there is nothing on this axis for a keyed object to name.
      */
     addColumn(values: CellValue[]): Cell[];
     /**
      * Append several columns after the last used column in one call, returning the cells materialised
-     * for each. The columns stack in order — the first lands at {@link columnCount}` + 1`, the next
-     * directly right of it — so a later column never collides with an earlier one even when both are
+     * for each. The columns stack in order: the first lands at {@link columnCount}` + 1`, the next
+     * directly right of it, so a later column never collides with an earlier one even when both are
      * value-less. The bulk form of {@link addColumn}.
      */
     addColumns(columns: CellValue[][]): Cell[][];
     /**
      * A snapshot of this sheet's value and overlay content (see {@link WorksheetModel}). Reading it and
-     * assigning it onto another sheet — `dst.model = src.model` — reproduces the source: merges, cells
-     * and their styles, column/row metadata, tables, the autofilter, protection, and the page setup all
-     * survive, because the getter emits and the setter consumes exactly the same fields. Identity
-     * (`name`, `id`) is not part of the model and is never touched by assignment; nor are attached parts
-     * that carry workbook-level identity (images, pivots, byte-preserved charts/drawings) — see
-     * {@link WorksheetModel} for that boundary.
+     * assigning it onto another sheet (`dst.model = src.model`) reproduces the source: merges, cells
+     * and their styles, column/row metadata, tables, the autofilter, protection, the frozen-pane view,
+     * and the page setup all survive, because the getter emits and the setter consumes exactly the same
+     * fields. Identity (`name`, `id`) is not part of the model and is never touched by assignment; nor
+     * are attached parts that carry workbook-level identity (images, pivots, threaded comments,
+     * byte-preserved charts/drawings). See {@link WorksheetModel} for that boundary.
      */
     get model(): WorksheetModel;
     set model(model: WorksheetModel);
@@ -602,7 +623,7 @@ export declare class Worksheet {
     /** The sheet's protection, or `undefined` if the sheet is unprotected. */
     get protection(): SheetProtection | undefined;
     /**
-     * The codec's channel into this sheet — see `core/internal.ts` for why these are not public
+     * The codec's channel into this sheet. See `core/internal.ts` for why these are not public
      * methods. Declared last so every private field it closes over is already in scope.
      */
     readonly [INTERNAL]: WorksheetInternals;
@@ -623,7 +644,7 @@ export interface WorksheetInternals {
      */
     evictRow(number: number): void;
     /**
-     * Register a pivot table reconstructed from a loaded package — the reader's counterpart to
+     * Register a pivot table reconstructed from a loaded package: the reader's counterpart to
      * {@link Worksheet.addPivotTable}. This records an inspectable, read-only view of a pivot the
      * reader parsed from its OOXML parts; the pivot itself round-trips by byte-preservation, so
      * registering it here only makes it visible via {@link Worksheet.loadedPivotTables} and never
@@ -635,7 +656,7 @@ export interface WorksheetInternals {
      * replacing any already held. Their authors and mentioned people are already resolved against the
      * workbook registry, so a thread arrives self-contained.
      *
-     * Not authoring — {@link Worksheet.addCommentThread} is that, and validates the anchor. These
+     * Not authoring: {@link Worksheet.addCommentThread} is that, and validates the anchor. These
      * threads are what a re-write emits, so what the reader hands over is what the file will say.
      */
     restoreCommentThreads(threads: readonly CommentThread[]): void;
@@ -646,7 +667,7 @@ export interface WorksheetInternals {
      */
     addPreservedReference(reference: PreservedWorksheetReference): void;
     /**
-     * Reinstate an already-derived protection state — the deserialization counterpart to
+     * Reinstate an already-derived protection state: the deserialization counterpart to
      * {@link Worksheet.protect}. A loaded `<sheetProtection>` carries its credential in finished agile
      * form (algorithm, hash, salt, spin count) with no recoverable plaintext password, so the reader
      * restores that credential verbatim rather than re-hashing.
@@ -655,7 +676,7 @@ export interface WorksheetInternals {
     /**
      * Materialise the cell at an exact 1-based position, creating it on first access. Unlike
      * {@link Worksheet.getCell} this performs no merge resolution: the cell returned is the one at
-     * `(row, col)` even when a merged region covers it. Loading content is where that matters — a
+     * `(row, col)` even when a merged region covers it. Loading content is where that matters: a
      * model or a parsed file states where each value sits, and routing a covered value to its region
      * master mid-load would move it.
      */