@sheetxl/query 0.7.28-beta.4 → 0.8.0-beta.10

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/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

@@ -0,0 +1,26 @@
+import { IRange, ISheet } 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.
+ *
+ * `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;
+/** `"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. */
+export declare function columnLetter(index: number): string;
+//# sourceMappingURL=findLabels.d.ts.map

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

@@ -1,6 +1,8 @@
+export * from './appendDependencies';
 export * from './appendSections';
 export * from './describeRegionPayload';
 export * from './describeRule';
+export * from './describeShape';
 export * from './describeStyle';
 export * from './MarkdownBuilder';
 export * from './parseRenderOptions';
@@ -11,8 +13,10 @@ export * from './renderConditionalFormat';
 export * from './renderCounts';
 export * from './renderDataValidation';
 export * from './renderFormula';
+export * from './renderModules';
 export * from './renderMovable';
 export * from './renderNames';
+export * from './renderProtection';
 export * from './renderRecords';
 export * from './renderRanges';
 export * from './renderRegions';

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

@@ -1,4 +1,5 @@
 import { ICellRange, ICellRegion } from '@sheetxl/sdk';
+import { FoundLabel } from './findLabels';
 /**
  * What {@link profileRegion} needs to read — the anchor cell and the extent, nothing a partition
  * knows that a plain range does not.
@@ -48,6 +49,10 @@ export interface ProfileRegionOptions {
  * exactly one, and a block has one per column (or row). This is the same discipline that keeps a
  * range from rendering cell facets — bounded by construction rather than by a limit that has to
  * fire.
+ *
+ * Data for a caller, never printed: a listing row already carries the size (`1×1`, `110×1`) and
+ * the header note, so a shape word beside them is a second vocabulary for the same fact — and
+ * `table` has to stay free to mean an authored {@link ITable}.
  */
 export type RegionShape = 'cell' | 'list' | 'table' | 'block';
 /**
@@ -58,7 +63,7 @@ export type RegionShape = 'cell' | 'list' | 'table' | 'block';
  */
 export interface RegionProfile {
     shape: RegionShape;
-    /** The one-line description that sits beside the address — `table · header row 1`. */
+    /** The one-line description that sits beside the address — `header row 1`, or a 1×1's value. */
     summary: string;
     /** One line per column (or row); empty for `cell` and `list`, whose profile is in `summary`. */
     series: string[];
@@ -88,6 +93,56 @@ export interface RegionProfile {
  *   elision is explicit, per the same rule that governs every truncated listing here.
  */
 export declare function profileRegion(region: ProfileSource, options?: ProfileRegionOptions): RegionProfile;
+/** A line the stats leave out, and why. */
+export interface TotalsLine {
+    /** Absolute row (or column, on a block profiled by row). */
+    index: number;
+    label: FoundLabel | null;
+    /** Set on the first line only when it was found by value: how it compares with the Σ above it. */
+    sums?: TotalsSums;
+}
+/** How a totals line's values compare with the sums of the body above them. */
+export interface TotalsSums {
+    matches: number;
+    candidates: number;
+    /** The line holds no formulas. */
+    typed: boolean;
+    /** The sums run down columns (the line is a row) rather than across rows. */
+    byColumn: boolean;
+    /** The cells that do not equal their Σ — `H26 text`, `C26 400 ≠ Σ 411`. */
+    misses: string[];
+}
+/** Where a block's body stops. */
+export interface Totals {
+    /** The block runs down its rows (`true`) or across its columns. */
+    byColumn: boolean;
+    /** Absolute index of the first line left out of the body. */
+    start: number;
+    /** Every line from {@link start} to the block's end. */
+    lines: TotalsLine[];
+    /** The profile summary's fragment — `rows 26:27 not profiled: …`. */
+    note: string;
+}
+/**
+ * Where a block's body stops: the first line whose values equal the Σ of the body above them.
+ *
+ * @remarks
+ * One deterministic test, the same for a `=SUM` row and a pasted one — a total equals the sum it
+ * totals by value, however it was entered. It needs two matches and a majority of the numeric
+ * series, so a coincidence in one column does not end a block. A table's totals row is taken as
+ * authored.
+ *
+ * Every line from there to the end of the block is left out of the stats, and each is named with
+ * its label so a reader can see what was set aside: the total, and whatever runs on below it
+ * (`Earnings Before Interest & Taxes` under `Total Expenses`). Labels are reported, never
+ * interpreted — deciding by its wording that a line is "a total" is the call a reader makes better.
+ *
+ * The first line's comparison is part of the fact: `typed` when it holds no formulas, and the cells
+ * that do not match, which on a pasted total are the finding.
+ */
+export declare function detectTotals(range: ICellRange, maxProfileCells?: number): Totals | null;
+/** `= Σ above (13 of 13)` / `typed, = Σ above (12 of 13; H26 text)` / `= Σ to the left (2 of 2)`. */
+export declare function describeSums(sums: TotalsSums): string;
 /**
  * Per-kind stats, pooled across the WHOLE range regardless of column — "what's actually in here,
  * broken down by type" in one shot, as opposed to {@link profileSeries}'s per-column breakdown.

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

@@ -1,7 +1,8 @@
 import { IWorkbook } from '@sheetxl/sdk';
-import { AppendDependencyOptions } from './appendSections';
+import { AppendDependencyOptions } from './appendDependencies';
 import { RenderCellRangeOptions } from './renderCellRange';
 import { RenderFormulaOptions } from './renderFormula';
+import { RenderModulesOptions } from './renderModules';
 import { RenderNamesOptions } from './renderNames';
 import { RenderRecordsOptions } from './renderRecords';
 import { RenderRangesOptions } from './renderRanges';
@@ -31,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 & AppendDependencyOptions;
+    type Options = RenderCellRangeOptions & RenderSheetOptions & RenderRegionsOptions & RenderValuesOptions & RenderFormulaOptions & RenderRecordsOptions & RenderNamesOptions & RenderRangesOptions & RenderModulesOptions & AppendDependencyOptions;
     /**
      * One renderable kind.
      */
@@ -54,6 +55,14 @@ export declare namespace Renderer {
  * must be read as a table rather than as its first element or as N reports.
  */
 export declare const RENDERERS: readonly Renderer.Entry[];
+/**
+ * The name of every renderable kind, in dispatch order.
+ *
+ * @remarks
+ * What a host's help text lists. Derived, because a hand-written copy of this list is a second
+ * registry that nothing keeps in step with the first.
+ */
+export declare const RENDERABLE_KINDS: readonly string[];
 /**
  * Thrown by {@link renderMarkdown} when nothing in the registry accepts the value.
  *

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

@@ -1,23 +1,26 @@
 import { ICell } from '@sheetxl/sdk';
-import { AppendDependencyOptions } from './appendSections';
+import { AppendDependencyOptions } from './appendDependencies';
 /**
- * Renders a cell's report: value, formula, spans, spill, the effective style, and its position in
- * the dependency graph.
+ * Renders a cell's report: value, formula, the block it sits in, whether it agrees with its
+ * siblings, its reach through the dependency graph, and the effective style.
  *
  * @remarks
+ * A cell is usually arrived at cold — a chat mention, a grep hit, a node in someone else's tree —
+ * so the report orients before it details: which block this is and what its labels say, whether
+ * this formula is the same as the ones beside it, and how much of the model it reads and feeds.
+ * Each of those is an index read, not a scan.
+ *
  * A cell is the one altitude where **resolved effect** belongs. A range reports style as authored
  * layers and never composes them, because composition is an expansion — a banded table is one
  * authored fact and an unbounded number of effective ranges. For a single cell the expansion is
  * one row, and "what does a human actually see here" is the question being asked, so `getStyle()`
- * is read rendered rather than direct.
- *
- * The dependency graph, by contrast, is NOT cell-only. It is indexed by range, so a range
- * answers the same four questions in one call and {@link renderCellRange} reports them too — the
- * cell form is that one over a 1×1.
+ * is read rendered rather than direct, and the line says so.
  *
  * 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. Value text goes through
- * {@link encodeCell}, so whatever this prints, grep can find.
+ * 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: `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): string;
+export declare function renderCell(cell: ICell, options?: AppendDependencyOptions): Promise<string>;
 //# sourceMappingURL=renderCell.d.ts.map

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

@@ -1,6 +1,7 @@
 import { ICellRange } from '@sheetxl/sdk';
 import { CellEncoding } from '../encode';
-import { AppendDependencyOptions, AppendFeatureOptions } from './appendSections';
+import { AppendDependencyOptions } from './appendDependencies';
+import { AppendFeatureOptions } from './appendSections';
 import { ProfileRegionOptions } from './profileRegion';
 /**
  * Options for {@link renderCellRange}.
@@ -57,5 +58,5 @@ export interface RenderCellRangeOptions extends AppendFeatureOptions, AppendDepe
  *
  * Cell text goes through {@link encodeCell}, so whatever a report prints, grep can find.
  */
-export declare function renderCellRange(range: ICellRange, options?: RenderCellRangeOptions): string;
+export declare function renderCellRange(range: ICellRange, options?: RenderCellRangeOptions): Promise<string>;
 //# sourceMappingURL=renderCellRange.d.ts.map

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

@@ -0,0 +1,55 @@
+import { IModule, IModuleCollection, IWorkbook } from '@sheetxl/sdk';
+import { MarkdownBuilder } from './MarkdownBuilder';
+/**
+ * Options for {@link renderModules} and {@link renderModule}.
+ */
+export interface RenderModulesOptions {
+    /** Maximum modules listed before the tail is reported as a count. */
+    maxModules?: number;
+    /** Maximum source lines shown per module in the full listing. */
+    maxSourceLines?: number;
+}
+/**
+ * Every module in the workbook, its own and its sheets', in one list.
+ *
+ * @remarks
+ * Both levels, because "does this workbook contain code" is one question and a reader who has to
+ * ask it per sheet will not ask it at all. Unfiltered by language — the default TypeScript filter
+ * exists to protect callers that only want runnable scripts, and this report exists precisely to
+ * say what is there.
+ */
+export declare function collectModules(workbook: IWorkbook): IModule[];
+/**
+ * Appends the code announcement — what has code, what runs itself, and what SheetXL will not run.
+ *
+ * @remarks
+ * **Names the modules that have source, and only those.** Excel writes an empty `ThisWorkbook`
+ * and an empty document module per sheet whether or not anyone wrote a line in them, so listing
+ * every module reports scaffolding as content — a five-row table for one macro, in which the
+ * reader has to work out which row matters. The heading still counts the whole collection, so
+ * nothing is hidden; the rows are the part worth reading, and `getModules()` reaches the rest.
+ *
+ * Nothing is printed for a workbook with no modules at all. Absence of code is the norm and does
+ * not need a section saying so.
+ */
+export declare function appendModules(md: MarkdownBuilder, modules: readonly IModule[], options?: RenderModulesOptions): void;
+/**
+ * Renders one module — its facts, then its source.
+ *
+ * @remarks
+ * The report that answers "what does this code do", which is why it prints the body rather than
+ * measuring it.
+ */
+export declare function renderModule(module: IModule, options?: RenderModulesOptions): string;
+/**
+ * Renders a module collection — the roster, then each module's source.
+ *
+ * @remarks
+ * **What it holds is decided by where the collection came from**, the same rule
+ * `renderNames` follows: `wb.getScripts().getModules()` is the workbook's own modules,
+ * `sheet.getModules()` is that sheet's. Neither is filtered here — a caller who reached this
+ * report asked to see what exists, so `language` is left wide open rather than defaulting to
+ * TypeScript the way an ordinary `getItems()` does.
+ */
+export declare function renderModules(modules: IModuleCollection, options?: RenderModulesOptions): string;
+//# sourceMappingURL=renderModules.d.ts.map

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

@@ -1,35 +1,104 @@
-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 {
+    movable: IMovable;
+    text: string;
+}
+/** The anchor as a plain A1 address — `toString()` may carry the sheet, and these rows decide that themselves. */
+export declare const describeAnchor: (movable: IMovable) => string;
+/** A shape's text as a listing prints it: quoted, capped, the recovery named where it was cut. */
+export declare const describeShapeText: ({ movable, text }: ShapeTextEntry) => string;
+/** The text written on a shape — `''` for a bare one — or `null` for content that is not a shape. */
+export declare const readShapeText: (movable: IMovable) => string | null;
 /**
- * `## Movables (3)` over `  C3:F12  chart  Chart 1 — column` rows — the pictures, charts, shapes
- * and slicers floating over the report's range.
+ * The shapes among `movables` that have something written on them, in reading order.
+ *
+ * @remarks
+ * **Only non-empty text.** On a shape with an empty body "no text" is itself the information: a
+ * bare rectangle is a box drawn around the cells under it.
+ *
+ * **Reading order, not z-order**: by the anchor's top-left, row-major. Z-order is the order the
+ * author happened to draw them in; callouts are written to be read down the sheet.
+ *
+ * Hidden shapes are included. Hidden text is exactly what a reviewer wants surfaced, and the row
+ * marks it so the reader knows a human looking at the grid does not see it.
+ */
+export declare function collectShapeText(movables: readonly IMovable[]): ShapeTextEntry[];
+/**
+ * One movable as one line of prose: `Picture 1 — logo.png`, or for a chart
+ * `line · 8 series · values NOI!C4:J111 · categories NOI!B4:B111 · Chart 2`.
+ *
+ * @remarks
+ * Name first because it is what the object is called everywhere else — the OOXML `cNvPr/@name`,
+ * the UI's selection pane — and because for a slicer or a shape it is the ONLY description
+ * anything can offer. A chart is the exception and its name goes last: `Chart 2` says nothing, and
+ * what the chart plots is the one fact on the row that points back at cells.
+ *
+ * The alt text joins it when set. It is prose a human wrote about a graphic a text report cannot
+ * show, so here it is not decoration: for a chart or a smart-art frame it is frequently the only
+ * sentence in the whole file that says what the graphic shows.
+ */
+export declare const describeMovableSummary: (movable: IMovable) => string;
+/** `Charts` for `chart` — a type the table does not know still gets a section, named after itself. */
+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[]>;
+/**
+ * One section per content type — `## Charts (1)`, `## Shapes (11 · 4 with text)` — over the
+ * pictures, charts, shapes and slicers floating over the report's range.
  *
  * @remarks
  * **The one class of sheet content that appears in no other section.** Everything else these
  * reports describe lives in cells and is reachable by address; a movable floats over the grid and
- * is invisible to every values, region and rule listing — so without this section a report about
- * a dashboard sheet says the sheet is nearly empty, which is true of its cells and false of what
+ * is invisible to every values, region and rule listing — so without these a report about a
+ * dashboard sheet says the sheet is nearly empty, which is true of its cells and false of what
  * anyone looking at it sees.
  *
- * Rows are `anchor · type · prose`, and both leading columns are arguments rather than labels: the
- * address is what `getRange()` takes, and the type is exactly what `getMovables({ type })` filters
- * on — the filter compares this same string.
+ * **A section per type, the way tables have one.** A reader looks for charts, or for the notes an
+ * author left; nobody looks for "movables", which is the SDK's word for how these are stored. The
+ * heading is the type, so no row spends a column repeating it.
+ *
+ * Rows are `anchor · preset · prose · "text"`. The anchor is what `getRange()` takes and says which
+ * cells the object is about; the preset says what kind of shape it is — a callout points at
+ * something, a text box stands alone. A chart's type takes the preset's column, and what it plots
+ * is labeled lines beneath its row, the way a table's facts are: a chart states three ranges, and
+ * on one line nothing says which is which.
  *
- * Listed in z-order, which is the order the collection returns them in and the order they paint,
- * so where two movables overlap the later row is the one on top. Hidden movables are listed and
- * marked; they are the ones a reader cannot otherwise learn about.
+ * **What is written on a shape rides its row, and those rows lead** — in reading order, ahead of
+ * the rest in z-order. Text on a shape is almost never decoration: it is a note from the author to
+ * the reader — what a block means, which cell to change, what not to touch — and the heading
+ * counts them so a reader knows to look. Leading also makes the cap safe: what it eats is bare
+ * rectangles. Hidden movables are listed and marked; they are the ones a reader cannot otherwise
+ * learn about.
  */
 export declare function appendMovables(md: MarkdownBuilder, movables: readonly IMovable[]): void;
 /**
- * Renders one movable's report — what it is, where it is anchored, and whether anyone can see it.
+ * Renders one movable's report — what it is, where it is anchored, and whether it is hidden.
  *
  * @remarks
- * The listing carries the identity; this adds what does not fit on a row: the pixel bounds, the
- * anchor behavior that decides what an insert does to this object, and the display note in full.
+ * The listing carries the identity; this adds what does not fit on a row: the pixel bounds and
+ * the anchor behavior that decides what an insert does to this object.
  *
  * **A movable has no name-based lookup**, so unlike a table this report leads with the anchor —
  * the address is how a reader gets back to it (`range.getMovables()`), and the name is the first
  * 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/renderNames.d.ts

@@ -24,9 +24,9 @@ export interface RenderNamesOptions extends AppendNamesOptions {
  * the workbook roster), and this is the report that has to be complete: a hidden broken name with
  * dependents is precisely the row a debugging agent must see, and the triage sort surfaces it.
  *
- * Synchronous, like every renderer: the dependents column is read off COMPILED formulas, so the
+ * The dependents column is the engine's answer, and it is read off COMPILED formulas, so the
  * caller settles the engine first — `renderMarkdown` settles its workbook argument before
  * dispatching here.
  */
-export declare function renderNames(names: INamedCollection, options?: RenderNamesOptions): string;
+export declare function renderNames(names: INamedCollection, options?: RenderNamesOptions): Promise<string>;
 //# sourceMappingURL=renderNames.d.ts.map

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

@@ -0,0 +1,81 @@
+import { ICellRange, ICell, IProtectedRange, IProtection, ISheet, ISheetProtection, IWorkbookProtection } from '@sheetxl/sdk';
+import { MarkdownBuilder } from './MarkdownBuilder';
+type AnyProtection = IProtection<any, any, any>;
+/**
+ * `locked · password` / `paused` — or `null` when the object is not protected.
+ *
+ * @remarks
+ * `null` is what every embedding report tests: an unprotected sheet says nothing about protection,
+ * at any altitude. Paused is reported because the document is still a protected one — it saves
+ * protected and `resume()` restores it — even though nothing is refused meanwhile. The password is
+ * only ever a word here; its hash and salt are never printed.
+ */
+export declare const describeLock: (protection: AnyProtection) => string | null;
+/**
+ * `structure locked · password` — the workbook report's `Protection:` line, or `null` when the
+ * workbook is not protected.
+ */
+export declare const describeWorkbookProtection: (protection: IWorkbookProtection) => string | null;
+/**
+ * A protected sheet's line on the workbook report — where it can still be written, and how much.
+ *
+ * @returns `null` when the sheet is not protected.
+ */
+export declare function summarizeSheetProtection(sheet: ISheet): {
+    extent: string;
+    detail: string;
+} | null;
+/**
+ * Appends a sheet report's `Protection` section — nothing at all when the sheet is not protected.
+ *
+ * @remarks
+ * Protection is a **precondition on writing**, the same reason a data validation is reported: a
+ * cell that will refuse the next write looks exactly like one that will accept it. So the section
+ * answers the writer's three questions in order — is it enforced, which operations survive, and
+ * where a value can still go.
+ *
+ * The editable regions are the `unlock` partition, which is why that feature has no section of its
+ * 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;
+/**
+ * A range report's `Protection:` line — how much of the range a write reaches — or `null` when the
+ * sheet is not locked.
+ *
+ * @remarks
+ * Locked only, not paused: this line is read immediately before a write, and a paused sheet
+ * refuses none.
+ */
+export declare function describeRangeProtection(range: ICellRange): string | null;
+/** A cell report's `Editable:` fact, or `null` when the sheet is not locked. */
+export declare function describeCellProtection(cell: ICell): string | null;
+/**
+ * The lookup that answers a write refused by protection, or `null` for any other failure.
+ *
+ * @remarks
+ * The refusal itself is written for a person at a dialog ("unprotect the sheet"); a script needs
+ * to know what is still allowed and where. Tested by `name`, since the error routinely crosses a
+ * bundle boundary on its way to the host that reports it.
+ */
+export declare function protectionPointerFor(error: unknown): string | null;
+/**
+ * Renders a sheet's or a workbook's protection — what `getProtection()` answers with.
+ *
+ * @remarks
+ * The object knows its options and not its owner, so this report carries no name and no cells: the
+ * editable regions are the sheet report's `Protection` section, and
+ * `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;
+/**
+ * Renders one unlocked range — a member of what `sheet.getProtectedRanges()` holds.
+ *
+ * @remarks
+ * Named for what it does rather than for its type: an `IProtectedRange` RELAXES protection, and a
+ * report titled "Protected Range" would tell a writer the opposite of the truth.
+ */
+export declare function renderProtectedRange(item: IProtectedRange): string;
+export {};
+//# sourceMappingURL=renderProtection.d.ts.map

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

@@ -49,6 +49,7 @@ export interface RenderRegionsOptions extends ProfileRegionOptions {
 export declare function appendRegionList(md: MarkdownBuilder, regions: readonly ICellRegion[], options?: RenderRegionsOptions & {
     payload?: RegionPayload;
     profile?: boolean;
+    series?: boolean;
 }): void;
 /**
  * Renders a partition — the unit `getRegions` returns, so an agent addresses structure instead

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

@@ -6,18 +6,17 @@ import { AppendFeatureOptions } from './appendSections';
 export interface RenderSheetOptions extends AppendFeatureOptions {
 }
 /**
- * Renders a markdown report of a sheet: counts, one section per feature partition, and the
- * sheet-level objects (named ranges, hidden headers, tables).
+ * Renders a markdown report of a sheet: counts, one section per feature partition, the sheet-level
+ * objects (named ranges, hidden headers, tables, pivot tables) and the floating layer by type.
  *
  * @remarks
  * **No `Values` section** — that one belongs to {@link renderCellRange}, where the caller named
  * bounds, and it is the only output in these reports that scales with the number of cells.
  *
  * Everything here is bounded by the sheet's structure instead: one section per feature
- * partition, and a profile per contentful block that reports computed shape (types, bounds,
- * aggregates, distinct counts) plus the text that names a block — a 1×1 prints its value, a
- * table its header labels. Blocks × series, both capped, so this report cannot grow with the
- * data. Altitude governs content: this one says where things are and what each block is; the
+ * partition, and one line per contentful block — its shape, its header, and the text that names
+ * it (a 1×1 prints its value). Per-column profiles summarize values, so they are the range
+ * report's. Altitude governs content: this one says where things are and what each block is; the
  * range report reads one.
  *
  * This is the whole-sheet form of the same stats a cell range reports — which is exactly why
@@ -25,5 +24,5 @@ export interface RenderSheetOptions extends AppendFeatureOptions {
  * then asked for, so the two calls compose into the whole read: this one to find the blocks,
  * that one to read one.
  */
-export declare function renderSheet(sheet: ISheet, options?: RenderSheetOptions): string;
+export declare function renderSheet(sheet: ISheet, options?: RenderSheetOptions): Promise<string>;
 //# sourceMappingURL=renderSheet.d.ts.map