@sheetxl/query 0.8.0-beta.10 → 0.8.0-beta.11

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sheetxl/query",
   "description": "SheetXL - Workbook read surface and renderers (grep, reports) — capabilities declared once, adapted by any host surface",
-  "version": "0.8.0-beta.10",
+  "version": "0.8.0-beta.11",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {
@@ -42,8 +42,8 @@
     "query"
   ],
   "dependencies": {
-    "@sheetxl/primitives": "^0.8.0-beta.10",
-    "@sheetxl/sdk": "^0.8.0-beta.10"
+    "@sheetxl/primitives": "^0.8.0-beta.11",
+    "@sheetxl/sdk": "^0.8.0-beta.11"
   },
   "devDependencies": {
     "@types/node": "^26.6.4"

package/types/src/api/_aliases.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Names a script reaches for from another spreadsheet API — Excel's, Office Scripts', openpyxl's —
+ * and where SheetXL keeps that concept. Each answer names the member it relies on, and is offered
+ * only while the index still has it.
+ */
+export declare const API_ALIASES: readonly {
+    readonly match: RegExp;
+    readonly relies: [string, string];
+    readonly hint: string;
+}[];
+/**
+ * The answer to a member called on a plain array (`wb.getSheets().getAt(0)`): `getAt`/`getItems`
+ * belong to a collection, and an array is indexed.
+ */
+export declare const arrayReceiverHint: (elementType: string) => string;
+//# sourceMappingURL=_aliases.d.ts.map

package/types/src/api/_offered.d.ts

@@ -0,0 +1,13 @@
+import { ScriptingApi } from '@sheetxl/sdk';
+/**
+ * Whether a declaration is offered. A `@deprecated` or `@hidden` one stays declared so a script that
+ * calls it still type-checks, and a lookup of its exact name still answers with its replacement; it
+ * is left out of listings, searches and suggestions, so nothing leads a reader to it.
+ */
+export declare const isOffered: (declared: {
+    readonly deprecated?: true;
+    readonly hidden?: true;
+}) => boolean;
+/** The members of `entry` that are {@link isOffered | offered}. */
+export declare const offeredMembers: (entry: ScriptingApi.Entry) => ScriptingApi.Member[];
+//# sourceMappingURL=_offered.d.ts.map

package/types/src/api/lookupApi.d.ts

@@ -66,7 +66,7 @@ export declare namespace ApiLookup {
      *
      * @remarks
      * A dotted name is a claim about where something lives, and the claim is what the reader needs
-     * corrected: `ISheets.add` wants to hear that the collection is `ISheetCollection`, and
+     * corrected: `ISheets.add` wants to hear that the collection is `IWorksheetCollection`, and
      * `ICellRange.setStyle` that a range's style is reached through `getStyle()`. A bare search for
      * `add` or `setStyle` lists every type that has one and leaves the claim standing.
      */
@@ -144,6 +144,14 @@ export declare function apiTypeOf(index: ScriptingApi.Index, target: unknown): s
  * generic or a primitive is not something the index answers for.
  */
 export declare function apiPointerFor(message: string, command: string): string | null;
+/**
+ * A compiler finding without its `Did you mean '…'?` when TypeScript means a member the index does
+ * not offer — a deprecated alias is still declared, so the compiler finds it nearest.
+ *
+ * @param message A compiler finding, e.g. `Property 'setFormat' does not exist on type 'ICellRange'.
+ * Did you mean 'getFormat'?`
+ */
+export declare function withoutHiddenSuggestion(index: ScriptingApi.Index, message: string): string;
 /**
  * The members nearest a name the script used and the API does not have — the answer an `api`
  * lookup would be asked for next, inline.

package/types/src/delta/describeDelta.d.ts

@@ -0,0 +1,148 @@
+import { IRange } from '@sheetxl/primitives';
+import { IWorkbook, IWorksheet } from '@sheetxl/sdk';
+/**
+ * What one commit did to a workbook, at region altitude: the structured half of the run delta.
+ *
+ * @remarks
+ * JSON-safe, so a host can send it as it is; {@link renderDelta} is its markdown. Every address is
+ * sheet-qualified and every list is capped, with the uncounted rest in a `more` field.
+ */
+export interface RunDelta {
+    /** The commit described. */
+    commitId: string;
+    /** One entry per sheet whose cells the commit changed. */
+    sheets: RunDelta.SheetChange[];
+    /** The cells downstream of the written ones, or `null` when nothing reads them. */
+    dependents: RunDelta.Dependents | null;
+    /** Errors now in the written and dependent cells, by region. */
+    errors: RunDelta.ErrorRegion[];
+    /** Error regions past {@link RunDelta.errors}. */
+    errorsMore: number;
+    /** Written cells that held an error before the commit and hold none now. */
+    errorsCleared: number;
+    /** What is not a cell, over the written or dependent cells. */
+    touches: RunDelta.Touches;
+}
+export declare namespace RunDelta {
+    /** What a commit did to one sheet. */
+    interface SheetChange {
+        /** The sheet, quoted as a reference would quote it. */
+        sheet: string;
+        /** The cells whose values or formulas were written, or `null` when none were. */
+        written: string | null;
+        /** Cells in {@link written}. */
+        cells: number;
+        /** Written cells that now hold a formula. */
+        formulas: number;
+        /** Written cells that now hold a value that is not a formula. */
+        values: number;
+        /** Written cells that are now empty. */
+        cleared: number;
+        /**
+         * What the write replaced, from the sheet as it was: populated cells and formulas among the
+         * written ones. `null` when it cannot be told: the commit moved cells, or the store no longer
+         * keeps the state before it.
+         */
+        replaced: {
+            populated: number;
+            formulas: number;
+        } | null;
+        /** The inserts and deletes of cells, in the order they ran. */
+        shifts: Shift[];
+        /** Ranges whose formatting changed, or `null`. */
+        styles: string | null;
+        /** The written formulas, one per block of the same formula. */
+        blocks: FormulaBlock[];
+        /** Blocks past {@link blocks}. */
+        blocksMore: number;
+    }
+    /** One insert or delete of cells. */
+    interface Shift {
+        kind: IWorksheet.ShiftKind;
+        /** The axis the neighboring cells moved along. */
+        axis: IRange.Axis;
+        /** The cells inserted or deleted, sheet-qualified; `null` when the state before was not kept. */
+        address: string | null;
+        /** Whole rows or columns, rather than cells within them. */
+        whole: boolean;
+    }
+    /** One written formula and the results it computed. */
+    interface FormulaBlock {
+        /** The block, sheet-qualified. */
+        address: string;
+        /** The formula as its first cell shows it, `=` included. */
+        formula: string;
+        /** Cells in the block. */
+        cells: number;
+        /** Results in reading order: all of them for a small block, else the first few and the last. */
+        values: string[];
+        /** `true` when {@link values} skips some, between its last two entries. */
+        sampled: boolean;
+    }
+    /** The cells downstream of the write. */
+    interface Dependents {
+        /** Populated dependent cells. */
+        cells: number;
+        /** The sheets they are on, with their cells. */
+        sheets: {
+            sheet: string;
+            cells: number;
+        }[];
+        /** Their areas, sheet-qualified. */
+        areas: string[];
+        /** Areas past {@link areas}. */
+        areasMore: number;
+    }
+    /** A region of one error, with its count. */
+    interface ErrorRegion {
+        /** Sheet-qualified. */
+        address: string;
+        /** The error as a cell shows it: `#VALUE!`, `#REF!`, … */
+        error: string;
+        /** Cells in the region. */
+        cells: number;
+    }
+    /** Objects over the written or dependent cells: listed, never evaluated. */
+    interface Touches {
+        /** Defined names over the written or dependent cells, or read through by a dependent. */
+        names: string[];
+        /** Conditional formats over the written or dependent cells, by their anchors. */
+        conditionalFormats: string[];
+        /** Data validations over the written or dependent cells, by their anchors. */
+        dataValidations: string[];
+        /** Charts that read the written cells or their dependents. */
+        charts: string[];
+    }
+}
+/** Options for {@link describeDelta}. */
+export interface DescribeDeltaOptions {
+    /**
+     * How many entries a list holds before the rest is counted: formula blocks, dependent areas,
+     * error regions.
+     *
+     * @defaultValue 20
+     */
+    maxEntries?: number;
+    /**
+     * How many results a formula block lists in full; a longer block lists its first few and its
+     * last.
+     *
+     * @defaultValue 8
+     */
+    maxBlockValues?: number;
+}
+/**
+ * Describes what a commit did, read from the workbook after its calculation settled.
+ *
+ * @param workbook The workbook the commit landed on, settled.
+ * @param commitId The commit. Omit for the current one.
+ * @returns `null` when the commit changed no cells.
+ *
+ * @remarks
+ * Nothing here is collected on the write path. The written ranges come from the commit
+ * ({@link IWorkbook.getChanges}), what they replaced from the sheet as it was at the commit before
+ * ({@link IWorksheet.ChangeEvent.getPreviousRanges}), and everything else is a read of the settled
+ * workbook bounded by what was written.
+ */
+export declare function describeDelta(workbook: IWorkbook, commitId?: string, options?: DescribeDeltaOptions): Promise<RunDelta | null>;
+//# sourceMappingURL=describeDelta.d.ts.map

package/types/src/delta/index.d.ts

@@ -0,0 +1,4 @@
+export * from './describeDelta';
+export * from './renderDelta';
+export * from './readRunDelta';
+//# sourceMappingURL=index.d.ts.map

package/types/src/delta/readRunDelta.d.ts

@@ -0,0 +1,21 @@
+import { IWorkbook } from '@sheetxl/sdk';
+import { DescribeDeltaOptions, RunDelta } from './describeDelta';
+/** What {@link readRunDelta} hands a run report. */
+export interface RunDeltaReport {
+    /** The delta, JSON-safe; absent when the commit changed no cells or it could not be read. */
+    delta?: RunDelta;
+    /** The report's lines: the delta rendered, or why it could not be read. */
+    markdown?: string;
+}
+/**
+ * The delta of a run's commit, as a run report carries it: the structure and its lines.
+ *
+ * @param workbook The workbook the run committed to, settled.
+ * @param commitId The run's commit; nothing is read without one (a run that wrote nothing).
+ *
+ * @remarks
+ * Never throws. The run has already committed, and a delta that cannot be read must not turn a
+ * write that landed into a reported failure, so the reason is reported in its place.
+ */
+export declare function readRunDelta(workbook: IWorkbook, commitId: string | undefined, options?: DescribeDeltaOptions): Promise<RunDeltaReport>;
+//# sourceMappingURL=readRunDelta.d.ts.map

package/types/src/delta/renderDelta.d.ts

@@ -0,0 +1,20 @@
+import { RunDelta } from './describeDelta';
+/**
+ * Renders a {@link RunDelta} as the lines a run report appends.
+ *
+ * @remarks
+ * One line per fact, labeled, so a reader scans the labels: what was written and what it
+ * replaced, the formulas with their results, what moved, what reads the write, the errors, and
+ * what sits over it that is not a cell.
+ *
+ * @example
+ * ```
+ * Changed:      Sheet1!H7:H38 — 32 formulas, 0 populated cells replaced
+ *   Sheet1!H7:H38  =B7*C7  → 12, 15, 18 … 90 (32 cells)
+ * Structure:    Sheet1!5:7 rows inserted
+ * Dependents:   212 cells on 2 sheets — Sheet1!K7:K38, Summary!B4:B9
+ * Errors:       Sheet1!K9:K12 #VALUE! (4)
+ * ```
+ */
+export declare function renderDelta(delta: RunDelta): string;
+//# sourceMappingURL=renderDelta.d.ts.map

package/types/src/encode/encodeCell.d.ts

@@ -45,6 +45,16 @@ export declare namespace CellEncoding {
          * format's category, and both of those are already reported.
          */
         readonly Value: "value";
+        /**
+         * The formula text where the cell has a formula (`=SUM(B2:B9)`), else its stored
+         * {@link Mode.Value | value}.
+         *
+         * @remarks
+         * Excel's Show Formulas view: for reading a block's logic as a grid. The inputs read as the
+         * scalars the formulas compute with — `0.25`, not `25%`; a date as its serial. The text carries
+         * its leading `=`, as the formula bar shows it.
+         */
+        readonly Formula: "formula";
     };
     type Mode = typeof Mode[keyof typeof Mode];
     /**

package/types/src/index.d.ts

@@ -4,6 +4,7 @@ export * from './encode';
 export * from './grep';
 export * from './api';
 export * from './markdown';
+export * from './delta';
 /**
  * The read surface, defined once.
  *

package/types/src/markdown/appendDependencies.d.ts

@@ -1,4 +1,4 @@
-import { ICellRange, ICellRanges, IRange, ISheet } from '@sheetxl/sdk';
+import { ICellRange, ICellRanges, IRange, IWorksheet } from '@sheetxl/sdk';
 import { MarkdownBuilder } from './MarkdownBuilder';
 /**
  * Options for the dependency sections.
@@ -36,7 +36,7 @@ export interface DependencyContext {
     /** Print `## Dependents (0)` rather than omitting the section. */
     zeroDependents?: boolean;
     /** The sheet the report is about; members elsewhere are listed as crossings. */
-    home?: ISheet | null;
+    home?: IWorksheet | null;
     /** The cells the report is about, when it is about cells: charts that plot them are dependents too. */
     subject?: ICellRange | null;
 }

package/types/src/markdown/appendSections.d.ts

@@ -1,4 +1,4 @@
-import { ICellRange, IAnchored, ICellRanges, ICellRegion, INamed, ISheet } from '@sheetxl/sdk';
+import { ICellRange, IAnchored, ICellRanges, ICellRegion, INamed, IWorksheet } from '@sheetxl/sdk';
 import { MarkdownBuilder } from './MarkdownBuilder';
 /**
  * Options for the feature sections.
@@ -92,7 +92,7 @@ export declare const describeExtent: (range: ICellRange) => string;
  */
 export declare const describeSheetName: (name: string | null | undefined) => string;
 /**
- * `wb.getSheet("My Sheet")` — the range's sheet as a callable expression.
+ * `wb.getWorksheet("My Sheet")` — the range's sheet as a callable expression.
  *
  * @remarks
  * Not {@link describeSheetName}: that quotes for the *formula* language (`'My Sheet'!A1`), and a
@@ -126,6 +126,17 @@ export declare const describeQualifiedExtent: (range: ICellRange) => string;
  * Zero kinds are elided, and blanks appear nowhere — empty is not a kind of content.
  */
 export declare function appendKinds(md: MarkdownBuilder, range: ICellRange): void;
+/**
+ * The role census: per role (`ICellRange.Feature.Role`), how many cells and the font colors they
+ * are written in — `input  36 · #0000FF 34 · #000000 2`.
+ *
+ * @remarks
+ * The pairing the `styleRole` check reads, laid out for the reader: the check names a link in
+ * the wrong color and says nothing about a typed cell, whose color reads like the data beside it,
+ * so the census carries the constants' colors and the reader judges them with the counts in
+ * hand. A color is the authored font color (`#RRGGBB`), the Normal style's where none is authored.
+ */
+export declare function appendRoles(md: MarkdownBuilder, range: ICellRange): void;
 /**
  * Appends one section per feature partition, headed by the feature's own name.
  *
@@ -256,7 +267,7 @@ export declare function appendNames(md: MarkdownBuilder, names: readonly INamed[
  * Counts only: the groups themselves (level, span, summary, collapsed) are `IOutline.getGroups`,
  * which is also what a script reads, so the report routes there instead of listing them.
  */
-export declare function describeOutline(sheet: ISheet): string | null;
+export declare function describeOutline(sheet: IWorksheet): string | null;
 /**
  * One rule listing — `## Conditional Formats (2)` over `  A1:D10  > 100 → fill #FFFF00` rows.
  *
@@ -273,11 +284,14 @@ export declare function describeOutline(sheet: ISheet): string | null;
  */
 export declare function appendRules<T extends IAnchored>(md: MarkdownBuilder, heading: string, items: readonly T[], describe: (item: T) => string): void;
 /**
- * The defined names whose target region intersects `range`, in collection order.
+ * The defined names whose target region intersects `range`, by name.
  *
  * @remarks
- * Scope-checked, not merely rectangle-checked: a name pointing at `Sheet2!A1:D4` overlaps this
- * sheet's `A1:D4` as coordinates and is a different region entirely. Defined names only — a
+ * Asked of the sheet's collection by address rather than resolved name by name here: the
+ * collection scope-checks (a name pointing at `Sheet2!A1:D4` overlaps this sheet's `A1:D4` as
+ * coordinates and is a different region entirely), and it resolves what the names designate as
+ * ONE step. A legacy file carries thousands of names nothing reads; asked one at a time, each
+ * compiled on its own, and a cell report over such a file ran out of memory. Defined names only — a
  * table's name has its own section.
  *
  * @param includeOwned Also admit this sheet's private names that designate no region

package/types/src/markdown/caps.d.ts

@@ -21,4 +21,8 @@
  * that would have to read further to find out.
  */
 export declare const pageWithLookahead: (total: number, pageSize: number) => number;
+/** `ICellRange.getValues()`'s default `maxSize`: a range over it is too big to copy out in one read. */
+export declare const GET_VALUES_LIMIT = 10000;
+/** The value sample a report prints for a range over {@link GET_VALUES_LIMIT}. */
+export declare const OVERSIZED_SAMPLE_CELLS = 200;
 //# sourceMappingURL=caps.d.ts.map

package/types/src/markdown/describeAnomaly.d.ts

@@ -0,0 +1,22 @@
+import { ICell, IRange } from '@sheetxl/sdk';
+/** The reader's name for each check, in the order a report lists them. */
+export declare const ANOMALY_LABELS: ReadonlyMap<string, string>;
+/** `inconsistent formula` — the label, or the check's own name for one without a label. */
+export declare const anomalyLabel: (check: string) => string;
+/**
+ * One finding as a reader's line, its positions read at `cell`: `inconsistent formula · the cells
+ * above and below have =B2*2`.
+ *
+ * @remarks
+ * The evidence holds positions relative to the cell (R1C1), which is what lets a filled row share
+ * one finding. Read at the region's anchor they become the addresses a next call takes.
+ */
+export declare function describeAnomaly(anomaly: ICell.Anomaly, cell: ICell): string;
+/** Every finding at `cell`, `;`-joined; `null` when none fires. */
+export declare function describeAnomalies(cell: ICell): string | null;
+/**
+ * R1C1 references in `text` as A1, read from `at`: `=R[-1]C*2` at `B3` is `=B2*2`. Absolute
+ * parts take a `$`, as Excel writes them.
+ */
+export declare function r1c1ToA1(text: string, at: IRange.CellCoords): string;
+//# sourceMappingURL=describeAnomaly.d.ts.map

package/types/src/markdown/describeChart.d.ts

@@ -1,4 +1,4 @@
-import { ISheet, ICellRange, ICellRanges, IChart, IMovable } from '@sheetxl/sdk';
+import { IWorksheet, ICellRange, ICellRanges, IChart, IMovable } from '@sheetxl/sdk';
 import { MarkdownBuilder } from './MarkdownBuilder';
 /** The chart a movable holds, or `null` for any other content. */
 export declare const chartOf: (movable: IMovable) => IChart | null;
@@ -49,7 +49,7 @@ export interface BrokenChartReference {
  * A broken series reference is an audit finding exactly like one in a formula — the chart has
  * stopped plotting what its author pointed it at — and no cell carries it, so no cell scan finds it.
  */
-export declare function collectBrokenChartReferences(sheet: ISheet): BrokenChartReference[];
+export declare function collectBrokenChartReferences(sheet: IWorksheet): BrokenChartReference[];
 /** A chart that plots the subject of a report, or something computed from it. */
 export interface ChartReader {
     movable: IMovable;

package/types/src/markdown/describeExternalCitation.d.ts

@@ -0,0 +1,27 @@
+import { ICalculation, IWorkbook } from '@sheetxl/sdk';
+/** One external citation that resolves to nothing, and why. */
+export interface BrokenExternalCitation {
+    /** The scope as the formula spells it: `'[1]ex 1 - ibo'`. */
+    scope: string;
+    /** `no external link [1] — this workbook has none`. */
+    reason: string;
+    /** How many references in the formula carry this scope. */
+    uses: number;
+}
+/**
+ * The external citations in a formula that resolve to nothing: a `[n]` past the workbook's links,
+ * or a sheet its link does not list. Each evaluates to `#REF!`.
+ *
+ * @remarks
+ * Excel stores a reference to a sheet that does not exist as a reference to another workbook, so
+ * `'[1]ex 1 - ibo'!F27` is often a misspelled local sheet whose link was later lost (LibreOffice
+ * drops every link on save and keeps the `[1]`). The scope's text is the only record of what was
+ * meant, so it is quoted back rather than summarized.
+ *
+ * A citation that binds is never reported. A DDE or OLE slot holds its position without a book, so
+ * a `[n]` naming one is not broken either.
+ */
+export declare function findBrokenExternalCitations(tokens: readonly ICalculation.FormulaToken[], workbook: IWorkbook | null | undefined): BrokenExternalCitation[];
+/** `cites '[1]ex 1 - ibo': no external link [1] — this workbook has none`, `; `-joined; `''` when none. */
+export declare function describeBrokenExternalCitations(citations: readonly BrokenExternalCitation[]): string;
+//# sourceMappingURL=describeExternalCitation.d.ts.map

package/types/src/markdown/describeHistogram.d.ts

@@ -1,4 +1,4 @@
-import { ICellRange, ICellRegion, IRange, ISheet, ICellStyle } from '@sheetxl/sdk';
+import { ICellRange, ICellRegion, IRange, IWorksheet, ICellStyle } from '@sheetxl/sdk';
 /**
  * Per-attribute histograms for the style feature sections.
  *
@@ -127,7 +127,7 @@ export interface StyleHistogram {
  * is only recognizable unclipped: the used-range view cuts `O:Q` to `O1:Q43` and it looks like a
  * block. Cell counts are then taken inside the used range, where finite numbers live.
  */
-export declare function describeStyleHistogram(sheet: ISheet, feature: ICellRange.Feature, normal: ICellStyle | null, options?: HistogramLineOptions & {
+export declare function describeStyleHistogram(sheet: IWorksheet, feature: ICellRange.Feature, normal: ICellStyle | null, options?: HistogramLineOptions & {
     /** The sheet's contentful rectangles, when the caller already has them (one partition serves every feature). */
     content?: readonly IRange.Coords[];
 }): StyleHistogram | null;

package/types/src/markdown/findLabels.d.ts

@@ -1,24 +1,17 @@
-import { IRange, ISheet } from '@sheetxl/sdk';
+import { IRange, IWorksheet } from '@sheetxl/sdk';
 /** A label and where it was read from. */
 export interface FoundLabel {
     text: string;
     address: string;
 }
 /**
- * The text that labels a cell's row (`'row'`) or column (`'column'`).
- *
- * @remarks
- * Deterministic, and the address is always returned so a reader can judge it:
- *
- * 1. The first cell of the line within the cell's current region (Ctrl+Shift+*), when it is text —
- *    the row label at the left edge of the block, the header at its top.
- * 2. Otherwise the nearest text cell before the cell on that line — leftward for a row, upward for
- *    a column. Only contentful cells are visited, so the walk costs the populated cells between,
- *    not the distance; there is no cap, because a cap is only a different arbitrary answer.
+ * The text that labels a cell's row (`'row'`) or column (`'column'`): the first text cell at the
+ * line's edge of the cell's current region, else the nearest text before it on that line. The
+ * SDK's label model, which the anomaly checks read too.
  *
  * `null` when the cell is itself the first cell of the line or nothing before it is text.
  */
-export declare function findLabel(sheet: ISheet, cell: IRange.CellCoords, axis: 'row' | 'column'): FoundLabel | null;
+export declare function findLabel(sheet: IWorksheet, cell: IRange.CellCoords, axis: 'row' | 'column'): FoundLabel | null;
 /** `"JUN" (G4)` — a label as the reports print it. */
 export declare const describeLabel: (label: FoundLabel | null) => string | null;
 /** 0-based column index to its A1 letter. */

package/types/src/markdown/index.d.ts

@@ -16,12 +16,13 @@ export * from './renderFormula';
 export * from './renderModules';
 export * from './renderMovable';
 export * from './renderNames';
+export * from './renderPageLayout';
 export * from './renderProtection';
 export * from './renderRecords';
 export * from './renderRanges';
 export * from './renderRegions';
 export * from './renderResult';
-export * from './renderSheet';
+export * from './renderWorksheet';
 export * from './renderStats';
 export * from './renderStyle';
 export * from './renderTable';

package/types/src/markdown/registry.d.ts

@@ -7,7 +7,7 @@ import { RenderNamesOptions } from './renderNames';
 import { RenderRecordsOptions } from './renderRecords';
 import { RenderRangesOptions } from './renderRanges';
 import { RenderRegionsOptions } from './renderRegions';
-import { RenderSheetOptions } from './renderSheet';
+import { RenderWorksheetOptions } from './renderWorksheet';
 import { RenderValuesOptions } from './renderValues';
 /**
  * The renderer registry: one entry per renderable kind.
@@ -18,7 +18,7 @@ import { RenderValuesOptions } from './renderValues';
  * Renderer.Entry.is}. Both paths land on the same entry, so a kind cannot render differently
  * depending on how it was reached.
  *
- * Detection uses the SDK's `isI*` runtime brands (`isIWorkbook`, `isISheet`, `isICellRange`,
+ * Detection uses the SDK's `isI*` runtime brands (`isIWorkbook`, `isIWorksheet`, `isICellRange`,
  * …) — the SDK's own convention for runtime type checking. The registry knows the SDK's
  * interfaces, never its classes, and a brand survives any transport that preserves methods.
  */
@@ -32,7 +32,7 @@ export declare namespace Renderer {
      * alternative is making the caller name the kind, which is the dispatch the registry exists
      * to remove.
      */
-    type Options = RenderCellRangeOptions & RenderSheetOptions & RenderRegionsOptions & RenderValuesOptions & RenderFormulaOptions & RenderRecordsOptions & RenderNamesOptions & RenderRangesOptions & RenderModulesOptions & AppendDependencyOptions;
+    type Options = RenderCellRangeOptions & RenderWorksheetOptions & RenderRegionsOptions & RenderValuesOptions & RenderFormulaOptions & RenderRecordsOptions & RenderNamesOptions & RenderRangesOptions & RenderModulesOptions & AppendDependencyOptions;
     /**
      * One renderable kind.
      */
@@ -99,6 +99,11 @@ export declare function resolveRenderer(target: unknown): Renderer.Entry | null;
  * and it is the whole async surface: the renderers themselves are synchronous, and a caller
  * invoking one directly is responsible for settling first.
  *
+ * A render can itself start calculation: a cell's effective style reads a conditional format
+ * whose whole-column answer is evaluated only where it is read, and the read asks for it. When a
+ * render leaves the engine calculating, it settles again and renders again, so the report carries
+ * what the first read asked for.
+ *
  * @throws If no registered renderer accepts the object.
  */
 export declare function renderMarkdown(workbook: IWorkbook | null, target: unknown, options?: Renderer.Options): Promise<string>;

package/types/src/markdown/renderFormula.d.ts

@@ -1,4 +1,4 @@
-import { ICalculation, ISheet } from '@sheetxl/sdk';
+import { ICalculation, IWorksheet } from '@sheetxl/sdk';
 /**
  * Options for {@link renderFormula}.
  */
@@ -20,7 +20,7 @@ export interface RenderFormulaOptions {
      * from `getReferences()`, and this option covers the case where it is not: a formula whose
      * references are all names or constants (`=TAX_RATE * 100`) resolves nothing without it.
      */
-    context?: ISheet;
+    context?: IWorksheet;
 }
 /**
  * Renders a formula's *analysis* report: its text, calculation status, behavioral flags, the

package/types/src/markdown/renderPageLayout.d.ts

@@ -0,0 +1,22 @@
+import { IPageLayout, IWorksheet } from '@sheetxl/sdk';
+/**
+ * The sheet report's `Print:` line — what differs from Excel's defaults — or `null` when nothing
+ * does.
+ *
+ * @remarks
+ * Built from the settings a reader acts on, not from `toJSON()`: a file routinely carries print
+ * state nobody chose (the printer's resolution, its opaque settings, the automatic breaks Excel
+ * last paginated with), and a sheet whose only print state is that is a default sheet.
+ */
+export declare function describePageLayout(sheet: IWorksheet): string | null;
+/**
+ * Renders a sheet's print layout — what `getPageLayout()` answers with.
+ *
+ * @remarks
+ * The page-shaping settings (orientation, paper, scale, margins, print area, titles, breaks) are
+ * always listed, marked when they are the default, so the report says how the sheet prints and not
+ * only how it differs. The rest is listed only when set: a line per default would bury the few that
+ * are not.
+ */
+export declare function renderPageLayout(layout: IPageLayout): string;
+//# sourceMappingURL=renderPageLayout.d.ts.map

package/types/src/markdown/renderProtection.d.ts

@@ -1,4 +1,4 @@
-import { ICellRange, ICell, IProtectedRange, IProtection, ISheet, ISheetProtection, IWorkbookProtection } from '@sheetxl/sdk';
+import { ICellRange, ICell, IProtectedRange, IProtection, IWorksheet, IWorksheetProtection, IWorkbookProtection } from '@sheetxl/sdk';
 import { MarkdownBuilder } from './MarkdownBuilder';
 type AnyProtection = IProtection<any, any, any>;
 /**
@@ -21,7 +21,7 @@ export declare const describeWorkbookProtection: (protection: IWorkbookProtectio
  *
  * @returns `null` when the sheet is not protected.
  */
-export declare function summarizeSheetProtection(sheet: ISheet): {
+export declare function summarizeSheetProtection(sheet: IWorksheet): {
     extent: string;
     detail: string;
 } | null;
@@ -38,7 +38,7 @@ export declare function summarizeSheetProtection(sheet: ISheet): {
  * own: on an unprotected sheet an unlocked cell refuses nothing and says nothing, and on a
  * protected one it is this section's body.
  */
-export declare function appendSheetProtection(md: MarkdownBuilder, sheet: ISheet): void;
+export declare function appendSheetProtection(md: MarkdownBuilder, sheet: IWorksheet): void;
 /**
  * A range report's `Protection:` line — how much of the range a write reaches — or `null` when the
  * sheet is not locked.
@@ -68,7 +68,7 @@ export declare function protectionPointerFor(error: unknown): string | null;
  * `sheet.getRegions("unlock")` on their own. An unprotected object still renders — the caller asked
  * — as the one line that says so, plus the options it keeps for its next lock.
  */
-export declare function renderProtection(protection: ISheetProtection | IWorkbookProtection): string;
+export declare function renderProtection(protection: IWorksheetProtection | IWorkbookProtection): string;
 /**
  * Renders one unlocked range — a member of what `sheet.getProtectedRanges()` holds.
  *

package/types/src/markdown/renderWorkbook.d.ts

@@ -21,7 +21,7 @@ export interface RenderWorkbookOptions extends Pick<AppendNamesOptions, 'maxName
  * regions and distinct formulas say how many ideas the model has, and distinct fonts and formats
  * say whether the styling is a convention. A layer that is empty has no line. The structure
  * behind each line is the sheet report's, and the `content` line carries that sheet's call
- * (`wb.getSheet("Sales") lists the blocks`): a reader routes by copying an address off the roster,
+ * (`wb.getWorksheet("Sales") lists the blocks`): a reader routes by copying an address off the roster,
  * so the call to the fuller report sits on the line the address is read from. **Twins** — sheets
  * whose formula partitions are identical, where the audit is the diff between them — are named on
  * the sheet.