@sheetxl/query 0.8.0-beta.2 → 0.8.0-beta.21

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

@@ -1,4 +1,4 @@
-import { ICellRange, IAnchored, ICellRanges, ICellRegion, INamed } from '@sheetxl/sdk';
+import { ICellRange, IAnchored, ICellRanges, ICellRegion, INamed, IWorksheet } from '@sheetxl/sdk';
 import { MarkdownBuilder } from './MarkdownBuilder';
 /**
  * Options for the feature sections.
@@ -20,6 +20,17 @@ export interface AppendFeatureOptions {
      * never produce a section.
      */
     features?: ICellRange.Feature | readonly ICellRange.Feature[];
+    /**
+     * The extent the layers authored over cells list over, when it is not the range's: the
+     * `Sparkline`, `Conditionals` and `DataValidations` sections.
+     *
+     * @remarks
+     * They are not cell content, so a layer over empty cells lies outside the used range a sheet
+     * report is scoped to, as it does in Excel's `UsedRange`. A sheet report passes the whole sheet,
+     * so a layer that exists is always reported. Direct style stays scoped to the range: a column
+     * style is a format, not a layer, and its cells are not used either.
+     */
+    layerScope?: ICellRange;
     /**
      * Cap on regions listed per feature; the report notes truncation when exceeded.
      *
@@ -92,7 +103,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 +137,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.
  *
@@ -196,6 +218,17 @@ export interface AppendNamesOptions {
      * since a bare `Sales` in an expression is a `named` token that resolves to a table.
      */
     symbols?: readonly INamed[];
+    /**
+     * Gives rows only to the names some formula reads; the rest are one count on the closing line.
+     *
+     * @defaultValue `false` — every name gets a row (a name manager must be complete)
+     *
+     * @remarks
+     * For a report whose job is routing. A name nothing reads changes no value and breaks no cell,
+     * and a decades-old model carries them by the ten thousand (macro-sheet constants, dead
+     * `#REF!`s): listed, they are the whole section; counted, the section is the names that matter.
+     */
+    omitUnread?: boolean;
 }
 /**
  * A name's spelling as a formula would write it — qualified when it is scoped to one sheet.
@@ -248,6 +281,15 @@ export declare const describeQualifiedName: (named: INamed) => string;
  * row is token noise, and blank-means-normal is how these reports already speak.
  */
 export declare function appendNames(md: MarkdownBuilder, names: readonly INamed[], options?: AppendNamesOptions): Promise<void>;
+/**
+ * The outline in a line — `rows 2 levels, 3 groups (1 collapsed) · columns 1 level, 1 group` —
+ * or `null` when nothing is grouped.
+ *
+ * @remarks
+ * 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: IWorksheet): string | null;
 /**
  * One rule listing — `## Conditional Formats (2)` over `  A1:D10  > 100 → fill #FFFF00` rows.
  *
@@ -264,11 +306,14 @@ export declare function appendNames(md: MarkdownBuilder, names: readonly INamed[
  */
 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,31 @@
+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, options?: {
+    constants?: boolean;
+}): string | null;
+/** A `constantFrequency` finding's constant as a formula types it: `12`, `"Total"`, `FALSE`. */
+export declare const describeConstant: (evidence: ICell.Anomaly["evidence"]) => string;
+/**
+ * Whether a region's findings are constants alone: the reports count those in the `Constants`
+ * census rather than listing each region among the breaks.
+ */
+export declare const isConstantOnly: (anomalies: readonly ICell.Anomaly[]) => boolean;
+/**
+ * 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, IStyle } 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: IStyle | 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;
@@ -181,6 +181,6 @@ export declare function describeKinds(range: ICellRange, formulaRegions: readonl
  * then there is no line; but a `Normal` that carries a fill or a number format paints every
  * untouched cell in the book, and no region reports it, because nobody authored it on a cell.
  */
-export declare function describeNormal(feature: ICellRange.Feature, normal: IStyle): string | null;
+export declare function describeNormal(feature: ICellRange.Feature, normal: ICellStyle): string | null;
 export {};
 //# sourceMappingURL=describeHistogram.d.ts.map

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

@@ -1,4 +1,4 @@
-import { ICellRange, ICellRegion, IStyle } from '@sheetxl/sdk';
+import { ICellRange, ICellRegion, ICellStyle } from '@sheetxl/sdk';
 /**
  * Describes one region's payload — the anchor cell's read for the feature that produced it.
  *
@@ -27,7 +27,7 @@ export interface RegionPayload {
  * lie of omission rather than a fact — see the TODOs below. The goal is that every partition
  * says something useful about what it found.
  */
-export declare function regionPayload(feature: ICellRange.Feature, normal: IStyle | null): RegionPayload | undefined;
+export declare function regionPayload(feature: ICellRange.Feature, normal: ICellStyle | null): RegionPayload | undefined;
 /**
  * One payload describer covering **every** feature a partition was built from.
  *
@@ -42,5 +42,5 @@ export declare function regionPayload(feature: ICellRange.Feature, normal: IStyl
  * an empty column, and a partition where none of them do returns `undefined` so the listing stays
  * addresses-only.
  */
-export declare function regionPayloads(features: readonly ICellRange.Feature[], normal: IStyle | null): RegionPayload | undefined;
+export declare function regionPayloads(features: readonly ICellRange.Feature[], normal: ICellStyle | null): RegionPayload | undefined;
 //# sourceMappingURL=describeRegionPayload.d.ts.map

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

@@ -1,4 +1,4 @@
-import { ICondition, IConditionalFormat, IDataValidation, IStyle } from '@sheetxl/sdk';
+import { ICondition, IConditionalFormat, IDataValidation, ICellStyle } from '@sheetxl/sdk';
 /**
  * The differential style a rule applies — the OOXML `dxf`, as the facets it actually names.
  *
@@ -7,7 +7,7 @@ import { ICondition, IConditionalFormat, IDataValidation, IStyle } from '@sheetx
  * property present in it is by construction something the rule author set. Absent facets are not
  * reported — a rule that only fills says `fill #FFFF00` and nothing about the font it leaves alone.
  */
-export declare const describeRuleStyle: (style: IStyle.Properties | null | undefined) => string | null;
+export declare const describeRuleStyle: (style: ICellStyle.Properties | null | undefined) => string | null;
 /**
  * A value→visual mapping — `colorScale · min #FFFFFF → max #FF0000`.
  *
@@ -46,9 +46,9 @@ export declare const describeDataValidation: (validation: IDataValidation) => st
  * @remarks
  * **A list validation IS a vocabulary**, and frequently the only place a sheet states one: what
  * `Region` is allowed to contain is exactly what a writer needs before writing, and what a reader
- * needs to recognize `ZZ` as wrong rather than as new. The rule text reports it as a count (`In 3
- * Items`) because a filter dropdown cannot show a hundred values, so a report that only carried the
- * rule left the vocabulary unreadable.
+ * needs to recognize `ZZ` as wrong rather than as new. The rule text reports a picked set as a
+ * count (`List 3 Items`) because a filter dropdown cannot show a hundred values, so a report
+ * that only carried the rule left the vocabulary unreadable.
  *
  * A list sourced from cells carries its formula instead of its values — that IS the answer, and it
  * is the address to read next.

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

@@ -0,0 +1,41 @@
+import { IShape, IGroup, IMovable, IMovableCollection } from '@sheetxl/sdk';
+import { MarkdownBuilder } from './MarkdownBuilder';
+/**
+ * A shape's text as one quoted row cell.
+ *
+ * @remarks
+ * Quoted, and never paraphrased, so it reads as what it is: content of the workbook, written by
+ * whoever could edit the file, not a statement of the report's. Newlines become a visible mark
+ * rather than a space because authors break lines on purpose — a callout listing three steps is
+ * three lines.
+ *
+ * @param max The cap, or `null` to print all of it.
+ * @param recovery The call that prints the rest; only read when the text is cut.
+ */
+export declare const quoteShapeText: (text: string, max: number | null, recovery: string) => string;
+/**
+ * The facts of a shape a report states beyond its placement: what it is, what it says, how it is
+ * drawn, what it links to and what it is glued to. Each fact only where the shape states it or it
+ * is not the default, so a plain rectangle stays a few lines.
+ *
+ * @remarks
+ * Read from the shape's JSON, which is the model: the accessors cover only its type, text and
+ * adjust values. A fill or line the shape does not state is named by where it comes from (its
+ * theme style) rather than resolved to a color — the theme is the workbook's, and the report says
+ * which reference to follow.
+ */
+export declare function appendShapeFacts(md: MarkdownBuilder, shape: IShape): void;
+/** `getContent()` as a group, when it is one. */
+export declare const groupOf: (movable: IMovable) => IGroup | null;
+/**
+ * A group's members, in z-order, one line each and indented by depth; a nested group's members
+ * beneath it. A picture is named by its file, a shape by its preset, and what is written on a
+ * member rides its line.
+ */
+export declare const appendGroupMembers: (md: MarkdownBuilder, members: IMovableCollection, depth: number) => void;
+/**
+ * The facts of a group a report states beyond its placement: what it holds, in z-order, and the
+ * fill it gives members that take the group's.
+ */
+export declare function appendGroupFacts(md: MarkdownBuilder, group: IGroup): void;
+//# sourceMappingURL=describeShape.d.ts.map

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

@@ -0,0 +1,15 @@
+import { ICellRange, ISparklineGroup } from '@sheetxl/sdk';
+/**
+ * `line of A2:E2 · group F2:F4 · high, low` — one cell's sparkline, as the cell report states it.
+ */
+export declare const describeSparkline: (sparkline: ISparklineGroup.ISparkline) => string;
+/**
+ * `line · reads A2:E4 · high, low` — the sparklines over `region`, one group's, as a region row
+ * states them.
+ *
+ * @remarks
+ * The cells read are spanned from the region's first and last sparkline, so this costs two
+ * lookups however many cells the region holds.
+ */
+export declare const describeSparklineRegion: (region: ICellRange) => string | null;
+//# sourceMappingURL=describeSparkline.d.ts.map

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

@@ -1,4 +1,4 @@
-import { IColor, IStyle } from '@sheetxl/sdk';
+import { IColor, ICellStyle } from '@sheetxl/sdk';
 /**
  * One-line descriptions of a style's authored facets.
  *
@@ -31,7 +31,7 @@ export declare const describeColor: (color: IColor | null | undefined) => string
  * paints for `solid` too. The fill's generic `getColor()` returns the *background*, which is
  * how a yellow cell once reported `pattern #000000 (auto)`.
  */
-export declare const describeFill: (style: IStyle) => string | null;
+export declare const describeFill: (style: ICellStyle) => string | null;
 /**
  * Describes borders — the edges that carry a style, each as `edge style color`.
  *
@@ -42,7 +42,7 @@ export declare const describeFill: (style: IStyle) => string | null;
  * `vertical` are `null` on a cell-scoped style, which is why the region payload reads through
  * `getRange()`.
  */
-export declare const describeBorder: (style: IStyle) => string | null;
+export declare const describeBorder: (style: ICellStyle) => string | null;
 /**
  * The border as a list of parts, identical edges grouped.
  *
@@ -54,11 +54,11 @@ export declare const describeBorder: (style: IStyle) => string | null;
  * genuinely distinct strokes produce distinct parts — which is what makes the multi-line form
  * (one part per line) worth printing.
  */
-export declare const describeBorderParts: (style: IStyle) => string[];
+export declare const describeBorderParts: (style: ICellStyle) => string[];
 /** Describes a number format — the format string itself is the payload. */
-export declare const describeNumberFormat: (style: IStyle) => string | null;
+export declare const describeNumberFormat: (style: ICellStyle) => string | null;
 /** Describes alignment — only the parts that differ from `normal`. */
-export declare const describeAlignment: (style: IStyle, normal: IStyle) => string | null;
+export declare const describeAlignment: (style: ICellStyle, normal: ICellStyle) => string | null;
 /** Describes a font — only the parts that differ from `normal`. */
-export declare const describeFont: (style: IStyle, normal: IStyle) => string | null;
+export declare const describeFont: (style: ICellStyle, normal: ICellStyle) => string | null;
 //# sourceMappingURL=describeStyle.d.ts.map

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

@@ -2,6 +2,7 @@ export * from './appendDependencies';
 export * from './appendSections';
 export * from './describeRegionPayload';
 export * from './describeRule';
+export * from './describeShape';
 export * from './describeStyle';
 export * from './MarkdownBuilder';
 export * from './parseRenderOptions';
@@ -15,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/renderCell.d.ts

@@ -19,7 +19,8 @@ import { AppendDependencyOptions } from './appendDependencies';
  * Facets that are not present are omitted rather than reported as absent — merge spans on an
  * unmerged cell, a spill range on a cell that is not spilled. Zeros that ARE facts are printed:
  * a formula nothing reads is an output, and `Dependents (0)` is how the report says it. Value text
- * goes through {@link encodeCell}, so whatever this prints, grep can find.
+ * goes through {@link encodeCell}, so whatever this prints, grep can find: `Display` is grep's
+ * `display` field and `Value` — the stored scalar, what `getValue()` returns — is its `value` field.
  */
 export declare function renderCell(cell: ICell, options?: AppendDependencyOptions): Promise<string>;
 //# sourceMappingURL=renderCell.d.ts.map

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/renderMovable.d.ts

@@ -1,4 +1,4 @@
-import { IMovable } from '@sheetxl/sdk';
+import { IMovable, IShape } from '@sheetxl/sdk';
 import { MarkdownBuilder } from './MarkdownBuilder';
 /** A shape with something written on it, the text already read. */
 export interface ShapeTextEntry {
@@ -45,6 +45,8 @@ export declare const describeTypeHeading: (type: string) => string;
 /**
  * `movables` by content type, in section order: the known types as {@link TYPE_HEADINGS} lists
  * them, then any other in the order it first appears. Z-order is kept within a type.
+ *
+ * A note's box is left out: the note is reported with the comments, and its box says nothing more.
  */
 export declare function groupMovables(movables: readonly IMovable[]): Map<string, IMovable[]>;
 /**
@@ -88,4 +90,15 @@ export declare function appendMovables(md: MarkdownBuilder, movables: readonly I
  * fact rather than the title.
  */
 export declare function renderMovable(movable: IMovable): string;
+/**
+ * Renders one shape's report: its placement, as {@link renderMovable} reports it, and everything
+ * the shape model states — geometry and adjust values, text and its layout, fill and line, line
+ * ends, links, locks, what a connector is glued to, and a group's members.
+ *
+ * @remarks
+ * The same report the shape's movable gives, titled for the object that was asked about: a shape
+ * is reached as `movable.getContent()`, and the reader should not have to step back to its movable
+ * to learn where it is.
+ */
+export declare function renderShape(shape: IShape): string;
 //# sourceMappingURL=renderMovable.d.ts.map

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/renderRecords.d.ts

@@ -8,6 +8,14 @@ export interface RenderRecordsOptions {
      * @defaultValue 1000
      */
     maxCells?: number;
+    /**
+     * The one-line form of a field that is a renderable SDK object, or `null` when it is not one.
+     *
+     * @remarks
+     * Supplied by the registry, which knows what renders; this renderer only knows that a class
+     * instance has no business being JSON-dumped. Without it such a field prints its string tag.
+     */
+    nested?: (value: unknown) => string | null;
 }
 /**
  * Whether a value is a *plain* object — an object literal or a `JSON.parse` result, nothing else.

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

@@ -50,7 +50,15 @@ export declare function appendRegionList(md: MarkdownBuilder, regions: readonly
     payload?: RegionPayload;
     profile?: boolean;
     series?: boolean;
+    collapse?: RegionKey;
 }): void;
+/** What a region says, as a key two regions saying the same thing share; `null` keeps it on its own. */
+export type RegionKey = (region: ICellRegion) => string | null;
+/**
+ * An `anomalies` region's key: its findings, check and evidence, without the rank. Two regions
+ * with the same findings are one line of the listing.
+ */
+export declare const anomalyRegionKey: RegionKey;
 /**
  * Renders a partition — the unit `getRegions` returns, so an agent addresses structure instead
  * of guessing ranges.

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

@@ -1,4 +1,4 @@
-import { IStyle } from '@sheetxl/sdk';
+import { ICellStyle } from '@sheetxl/sdk';
 /**
  * Renders a style report: the named style it derives from, plus its direct overrides.
  *
@@ -8,5 +8,5 @@ import { IStyle } from '@sheetxl/sdk';
  * the style model grows. No direct properties means the style is entirely inherited; the
  * report says so instead of enumerating absence (the closed-world contract).
  */
-export declare function renderStyle(style: IStyle): string;
+export declare function renderStyle(style: ICellStyle): string;
 //# sourceMappingURL=renderStyle.d.ts.map

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

@@ -1,5 +1,7 @@
-import { ITable } from '@sheetxl/sdk';
+import { ICell, ITable } from '@sheetxl/sdk';
 import { MarkdownBuilder } from './MarkdownBuilder';
+/** The table a cell is in, or `null`. The sheet's autofilter is not a table. */
+export declare const tableOf: (cell: ICell) => ITable | null;
 /**
  * `## Tables (981 cells · 1 table)` over one `B3:J111  109×9  tblNOI` row per table, its facts
  * indented beneath it.

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.