@sheetxl/query 0.7.23-beta.1

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

@@ -0,0 +1,66 @@
+import { ICondition, IConditionalFormat, IDataValidation, IStyle } from '@sheetxl/sdk';
+/**
+ * The differential style a rule applies — the OOXML `dxf`, as the facets it actually names.
+ *
+ * @remarks
+ * Not a diff against `Normal` like a style region's payload: a dxf **is** already a diff, so every
+ * 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;
+/**
+ * A value→visual mapping — `colorScale · min #FFFFFF → max #FF0000`.
+ *
+ * @remarks
+ * The three band rules are not predicates, so there is no condition to print for them. What
+ * describes one is the mapping itself: the kind, and the thresholds it maps between, in the order
+ * they were authored.
+ */
+export declare const describeScale: (scale: IConditionalFormat.Scale) => string;
+/**
+ * A conditional format as one line — the predicate, then what it paints.
+ *
+ * @remarks
+ * `> 100 → fill #FFFF00` is the whole fact: a rule is a test plus an effect, and either half alone
+ * leaves the reader with the other to guess. A band rule (color scale, data bar, icon set) has no
+ * predicate and renders itself, so it prints as its mapping and nothing follows the arrow.
+ *
+ * `stop if true` is appended where set, because it changes what the rules BELOW this one do — a
+ * later rule that appears to apply may never be reached.
+ */
+export declare const describeConditionalFormat: (format: IConditionalFormat) => string;
+/**
+ * A data validation as one line — the predicate, then the marks that change what it permits.
+ *
+ * @remarks
+ * The alert style is stated on every row rather than elided as a default, the one place these
+ * reports do that: it is the difference between a rule that REFUSES the next write (`stop`) and one
+ * that merely comments on it, an omission cannot carry that, and there is no default a reader could
+ * assume — Excel writes `stop` while a rule built here starts at `information`. `blanks allowed` is
+ * Excel's *Ignore blank*, which decides whether an empty cell is a violation.
+ */
+export declare const describeDataValidation: (validation: IDataValidation) => string;
+/**
+ * The values a list validation admits, spelled out — or the formula the list is read from.
+ *
+ * @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.
+ *
+ * A list sourced from cells carries its formula instead of its values — that IS the answer, and it
+ * is the address to read next.
+ */
+export declare const describeAllowedValues: (condition: ICondition | null | undefined) => string | null;
+/**
+ * The rules covering one region, joined for a single listing row.
+ *
+ * @remarks
+ * Separated by ` | ` rather than the ` · ` a single rule uses for its own marks — overlapping rules
+ * are common (that is why a cell can carry several), and one separator for both levels made a
+ * two-rule row unreadable as either.
+ */
+export declare const describeRules: <T>(items: readonly T[], describe: (item: T) => string) => string | null;
+//# sourceMappingURL=describeRule.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"describeRule.d.ts","sourceRoot":"","sources":["../../../../src/markdown/describeRule.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EAAE,kBAAkB,EACjB,KAAK,eAAe,EAAE,KAAK,MAAM,EAC/C,MAAM,cAAc,CAAC;AAqFtB;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,CAAC,UAAU,GAAG,IAAI,GAAG,SAAS,KAAG,MAAM,GAAG,IAmCxF,CAAC;AAWF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,kBAAkB,CAAC,KAAK,KAAG,MAW/D,CAAC;AAKF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,GAAI,QAAQ,kBAAkB,KAAG,MAYtE,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,GAAI,YAAY,eAAe,KAAG,MAOpE,CAAC;AAKF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,GAAI,WAAW,UAAU,GAAG,IAAI,GAAG,SAAS,KAAG,MAAM,GAAG,IAUzF,CAAC;AAKF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,EAC7B,OAAO,SAAS,CAAC,EAAE,EACnB,UAAU,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,KAC5B,MAAM,GAAG,IAKX,CAAC"}

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

@@ -0,0 +1,64 @@
+import { IColor, IStyle } from '@sheetxl/sdk';
+/**
+ * One-line descriptions of a style's authored facets.
+ *
+ * @remarks
+ * These are the *payloads* of the style feature regions (`Fill`, `Border`, `NumberFormat`,
+ * `Alignment`, `Font`): a region is uniform by construction, so the anchor cell's read
+ * describes every cell in it.
+ *
+ * Each facet is described **against the workbook's `Normal` style** rather than dumped whole.
+ * A resolved style has ~40 properties and a region carries one or two authored ones; printing
+ * the resolution buries the fact. The diff is what the author actually did — the authored
+ * layer, per the read surface's style rule.
+ */
+/**
+ * Formats a color as RGB, carrying its symbolic origin when it has one — `#000000 (dk1)`.
+ *
+ * @remarks
+ * A theme slot, an indexed color or a tint is not a color: an audit cannot compare `dk1` to
+ * `#000000` without resolving it. The origin is kept alongside because a themed color and a
+ * literal one that happen to match are different authoring decisions.
+ */
+export declare const describeColor: (color: IColor | null | undefined) => string | null;
+/**
+ * Describes a fill — `solid #FFFF00`, `darkGray pattern #FF0000 on #FFFFFF`, `gradient`.
+ *
+ * @remarks
+ * **The visible color of a pattern fill is the FOREGROUND.** A plainly-filled yellow cell is a
+ * pattern fill with patternType `solid` and a yellow foreground; the background is the color
+ * BEHIND the pattern marks (`auto` on a plain fill) — it is exactly what the CSS renderer
+ * 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;
+/**
+ * Describes borders — the edges that carry a style, each as `edge style color`.
+ *
+ * @remarks
+ * **Includes the inner rules when the style knows its extent.** A bordered block is very often a
+ * box *with a grid inside it*, and the four outer edges cannot say so — a payload that stops at
+ * the outline reports "thin box" for a table and for a boxed blank cell alike. `horizontal` and
+ * `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;
+/**
+ * The border as a list of parts, identical edges grouped.
+ *
+ * @remarks
+ * The overwhelmingly common authored border is the SAME stroke on several edges — a boxed range
+ * is four identical edges, and listing `top thick X · left thick X · bottom thick X · right
+ * thick X` says one fact four times. Edges sharing a stroke collapse into one part: all four
+ * outer edges become **`outline`**, any other run lists its edges (`top+bottom thin`). Only
+ * 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[];
+/** Describes a number format — the format string itself is the payload. */
+export declare const describeNumberFormat: (style: IStyle) => string | null;
+/** Describes alignment — only the parts that differ from `normal`. */
+export declare const describeAlignment: (style: IStyle, normal: IStyle) => string | null;
+/** Describes a font — only the parts that differ from `normal`. */
+export declare const describeFont: (style: IStyle, normal: IStyle) => string | null;
+//# sourceMappingURL=describeStyle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"describeStyle.d.ts","sourceRoot":"","sources":["../../../../src/markdown/describeStyle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,MAAM,EAAE,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAE/D;;;;;;;;;;;;GAYG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,MAAM,GAAG,IAgBzE,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,MAAM,GAAG,IAkBrD,CAAC;AAKF;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,MAAM,GAAG,IAGvD,CAAC;AAKF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,MAAM,KAAG,MAAM,EA6BzD,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,oBAAoB,GAAI,OAAO,MAAM,KAAG,MAAM,GAAG,IAG7D,CAAC;AAEF,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,EAAE,QAAQ,MAAM,KAAG,MAAM,GAAG,IAU1E,CAAC;AAEF,mEAAmE;AACnE,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,EAAE,QAAQ,MAAM,KAAG,MAAM,GAAG,IAcrE,CAAC"}

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

@@ -0,0 +1,27 @@
+export * from './appendSections';
+export * from './describeRegionPayload';
+export * from './describeRule';
+export * from './describeStyle';
+export * from './MarkdownBuilder';
+export * from './parseRenderOptions';
+export * from './profileRegion';
+export * from './renderCell';
+export * from './renderCellRange';
+export * from './renderConditionalFormat';
+export * from './renderCounts';
+export * from './renderDataValidation';
+export * from './renderFormula';
+export * from './renderMovable';
+export * from './renderNames';
+export * from './renderRecords';
+export * from './renderRanges';
+export * from './renderRegions';
+export * from './renderResult';
+export * from './renderSheet';
+export * from './renderStats';
+export * from './renderStyle';
+export * from './renderTable';
+export * from './renderValues';
+export * from './renderWorkbook';
+export * from './registry';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/markdown/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC"}

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

@@ -0,0 +1,16 @@
+import { Renderer } from './registry';
+/** The legal keys, in declaration order — what an error message lists. */
+export declare const RENDER_OPTION_KEYS: readonly string[];
+/**
+ * Parses a host's string-valued render options into a {@link Renderer.Options}.
+ *
+ * @remarks
+ * An unknown key **throws with the whole vocabulary**, for the reason `parseFeatures` does: a
+ * silently dropped option reads as "the report ignored what I asked for", which sends the reader
+ * looking for the bug in the renderer rather than in what they typed.
+ *
+ * Values arrive as strings because that is what a command line and a JSON string map carry; a
+ * caller already holding typed options should build {@link Renderer.Options} directly.
+ */
+export declare function parseRenderOptions(raw: Readonly<Record<string, string>>): Renderer.Options;
+//# sourceMappingURL=parseRenderOptions.d.ts.map

package/types/src/markdown/parseRenderOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseRenderOptions.d.ts","sourceRoot":"","sources":["../../../../src/markdown/parseRenderOptions.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AA8B3C,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAAyB,CAAC;AAY1E;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,OAAO,CAU1F"}

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

@@ -0,0 +1,121 @@
+import { ICellRange, ICellRegion } from '@sheetxl/sdk';
+/**
+ * What {@link profileRegion} needs to read — the anchor cell and the extent, nothing a partition
+ * knows that a plain range does not.
+ *
+ * @remarks
+ * `ICellRegion` satisfies this structurally, so every existing caller (a `Contentful` partition's
+ * members) needs no change. It also lets a bare {@link ICellRange} profile itself — `renderCellRange`
+ * adapts one with a four-line object, `getRange` returning the range itself — without a region ever
+ * having been asked for.
+ */
+export type ProfileSource = Pick<ICellRegion, 'getRowCount' | 'getColumnCount' | 'getCell' | 'getRange'>;
+/**
+ * Options for {@link profileRegion}.
+ */
+export interface ProfileRegionOptions {
+    /**
+     * Series (columns, or rows on a wide block) described before the profile elides the rest.
+     *
+     * @defaultValue 24
+     */
+    maxSeries?: number;
+    /**
+     * Cells scanned per region. Above this the profile is taken from a leading slice and **says
+     * so** — the alternative is a report whose cost is unbounded in the size of the sheet.
+     *
+     * @remarks
+     * A scan budget, not a listing cap: it bounds what profiling *reads*, where every other `max*`
+     * bounds what a report *prints*. The distinction is the reason for the name — spelled
+     * `maxCells` it merged with `RenderCellRangeOptions.maxCells` on `Renderer.Options`, where one
+     * value silently shrank the values table *and* put every profile on a leading slice.
+     *
+     * @defaultValue 20000
+     */
+    maxProfileCells?: number;
+    /**
+     * Distinct values listed for a categorical series before `…`.
+     *
+     * @defaultValue 3
+     */
+    maxCategories?: number;
+}
+/**
+ * What a contentful region turned out to be.
+ *
+ * @remarks
+ * The three shapes are structural, not tunable: a 1×1 has no series to describe, a 1-D run has
+ * 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.
+ */
+export type RegionShape = 'cell' | 'list' | 'table' | 'block';
+/**
+ * A contentful region's profile: what the block IS, and one line per series inside it.
+ *
+ * @remarks
+ * `summary` rides the region's address line; `series` are the indented lines beneath it.
+ */
+export interface RegionProfile {
+    shape: RegionShape;
+    /** The one-line description that sits beside the address — `table · header row 1`. */
+    summary: string;
+    /** One line per column (or row); empty for `cell` and `list`, whose profile is in `summary`. */
+    series: string[];
+}
+/**
+ * Profiles a **contentful** region — the answer to "what is actually in this block?".
+ *
+ * @remarks
+ * `Contentful` is the one feature whose regions carry no payload: every other feature partitions
+ * on payload identity (a `Fill` region is one color, a `Formula` region one authored R1C1), so its
+ * anchor read describes the block. Occupancy has no such identity — a contentful region is pure
+ * geometry, which is why the listing could only ever print an address and a size, and why an agent
+ * had to spend one round trip per block to learn anything at all. Twelve blocks, twelve calls.
+ *
+ * So the payload is **computed** rather than read: per-series counts, types and aggregates, which
+ * is `df.info()` + `df.describe()` — the shape every reader already knows, and the one openpyxl
+ * cannot produce. Nothing here is new engine work; it is `getStats` and `getCounts` per series,
+ * arranged.
+ *
+ * Three rules keep it honest:
+ *
+ * - **A header is detected, never assumed**, and the result is stated either way. A silently
+ *   assumed header shifts every label by one column and the reader cannot tell.
+ * - **The longer axis is the series axis**, and the profile says which. Profiling a 3×40 block by
+ *   column would print forty lines describing nothing.
+ * - **Above {@link ProfileRegionOptions.maxProfileCells} the scan is a leading slice and says so** —
+ *   elision is explicit, per the same rule that governs every truncated listing here.
+ */
+export declare function profileRegion(region: ProfileSource, options?: ProfileRegionOptions): RegionProfile;
+/**
+ * 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.
+ *
+ * @remarks
+ * `Number` and the categorical kinds are naturally kind-isolated by the stats machinery already,
+ * with no partition and no new index required: `getAggregates` is computed over the numeric
+ * population regardless of what else shares the range, and `getFrequencies({ filterFn })`
+ * restricts distinctness to one kind. Each line leads with the count, exactly like the bare
+ * `Number: N` a `Types` section already prints — this is that line, with the stats appended.
+ *
+ * `Date` is left out here, on cost rather than ability: computing it correctly means a value scan
+ * (see {@link countDates}) rather than a `getCounts`/`getStats` read, and this payload is the
+ * CHEAP alternative to full per-column profiling — a Contentful region listing that pays for a
+ * date scan on every unprofiled row has lost the reason it exists. `appendKinds`, called once per
+ * report rather than once per listed region, affords it.
+ */
+export declare function profileKinds(range: ICellRange, maxCategories?: number): string[];
+/**
+ * How many cells in `range` are genuinely dates — numeric value AND date-category format, read
+ * directly off each value the same way `getInteropType()` already classifies it for display.
+ *
+ * @remarks
+ * Not `range.getCounts([Feature.DateFormat])`: that counts the FORMAT alone — a blank cell or a
+ * text cell carrying a date-category format counts there too, which is the wrong, looser
+ * condition for "how many of these are dates". `DateFormat` is deliberately just a formatting
+ * predicate now (see `ICellRange.Feature`'s own remarks); this is the value-level question a
+ * report asks instead, composed from public API rather than any single feature.
+ */
+export declare function countDates(range: ICellRange): number;
+//# sourceMappingURL=profileRegion.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"profileRegion.d.ts","sourceRoot":"","sources":["../../../../src/markdown/profileRegion.ts"],"names":[],"mappings":"AAAA,OAAO,EAC0B,UAAU,EAAE,KAAK,WAAW,EAC5D,MAAM,cAAc,CAAC;AAMtB;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW,EAAE,aAAa,GAAG,gBAAgB,GAAG,SAAS,GAAG,UAAU,CAAC,CAAC;AAEzG;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,WAAW,CAAC;IACnB,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAC;IAChB,gGAAgG;IAChG,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,aAAa,CAiFlG;AAuLD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,aAAa,GAAE,MAAU,GAAG,MAAM,EAAE,CAqBnF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAMpD"}

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

@@ -0,0 +1,96 @@
+import { IWorkbook } from '@sheetxl/sdk';
+import { AppendDependencyOptions } from './appendSections';
+import { RenderCellRangeOptions } from './renderCellRange';
+import { RenderFormulaOptions } from './renderFormula';
+import { RenderNamesOptions } from './renderNames';
+import { RenderRecordsOptions } from './renderRecords';
+import { RenderRangesOptions } from './renderRanges';
+import { RenderRegionsOptions } from './renderRegions';
+import { RenderSheetOptions } from './renderSheet';
+import { RenderValuesOptions } from './renderValues';
+/**
+ * The renderer registry: one entry per renderable kind.
+ *
+ * @remarks
+ * Two consumers, one list. `describe` resolves an explicit kind (`'sheet'`) by name; dynamic
+ * surfaces (the REPL's `.md`, a macro result) resolve an arbitrary SDK object via {@link
+ * 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`,
+ * …) — 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.
+ */
+export declare namespace Renderer {
+    /**
+     * Everything any registered renderer accepts.
+     *
+     * @remarks
+     * The registry dispatches on the object, not the caller, so one options bag has to reach
+     * whichever entry matched. Each renderer reads the keys it knows and ignores the rest — the
+     * 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;
+    /**
+     * One renderable kind.
+     */
+    interface Entry<T = any> {
+        /** Registry key — the kind name an explicit lookup (`describe('sheet', …)`) uses. */
+        readonly kind: string;
+        /** Detects whether this entry accepts the object — the dynamic-dispatch path. */
+        is(target: unknown): target is T;
+        /** Renders the object as its markdown report. */
+        render(target: T, options?: Options): string | Promise<string>;
+    }
+}
+/**
+ * All renderable kinds, most specific first — dynamic dispatch takes the first match.
+ *
+ * @remarks
+ * The structural entries (`values`, `records`, `record`, `items`) come last because their detection
+ * is shape-based rather than branded, so every kind that *does* carry a brand gets first refusal.
+ * `record` and `items` are last of all: they are the widest shapes here, and an array of records
+ * must be read as a table rather than as its first element or as N reports.
+ */
+export declare const RENDERERS: readonly Renderer.Entry[];
+/**
+ * Thrown by {@link renderMarkdown} when nothing in the registry accepts the value.
+ *
+ * @remarks
+ * A distinct type because "nothing renders this" is a ROUTING answer, and callers fall back on
+ * it — {@link renderResult} summarizes the value in one line instead. A renderer that throws
+ * while rendering is a different event entirely: it means the report is broken, and reporting it
+ * as "no renderer" sends the reader off to `--json` for a value that has a perfectly good
+ * renderer. Without a type to test, the two are indistinguishable and the real error is lost.
+ */
+export declare class NoRendererError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolves the registry entry for an arbitrary object, or `null` if nothing renders it.
+ */
+export declare function resolveRenderer(target: unknown): Renderer.Entry | null;
+/**
+ * Renders any renderable SDK object as its markdown report.
+ *
+ * @param workbook The workbook whose calculation settles before the render — the book the target
+ * came from. `null` only for a value with no book behind it (a plain array, a record).
+ *
+ * @remarks
+ * Unbranded iterables (a generator a macro returned, `find()`'s iterator) are materialized —
+ * capped — before dispatch, so a bare iterator still renders as whatever its members are.
+ * Branded kinds never take this path: `getRegions` returns a branded collection that happens to
+ * be iterable, and flattening it would lose the features it carries.
+ *
+ * **Calculation settles here, not in the renderers.** A report read before the engine drains is
+ * wrong in quiet ways — formula results absent, used ranges short, every name reported unused —
+ * which is why the workbook is the FIRST parameter rather than an option a caller can forget.
+ * One settle covers every kind (all of a book's sheets, names and formulas share its engine),
+ * and it is the whole async surface: the renderers themselves are synchronous, and a caller
+ * invoking one directly is responsible for settling first.
+ *
+ * @throws If no registered renderer accepts the object.
+ */
+export declare function renderMarkdown(workbook: IWorkbook | null, target: unknown, options?: Renderer.Options): Promise<string>;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../../src/markdown/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAE+D,SAAS,EACnF,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,KAAK,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAEhE,OAAO,EAAmB,KAAK,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAIjF,OAAO,EAAiB,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAE3E,OAAO,EAAe,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EAAgC,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC1F,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EAAiB,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EAAe,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAIrE,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGxE;;;;;;;;;;;;GAYG;AACH,yBAAiB,QAAQ,CAAC;IACxB;;;;;;;;OAQG;IACH,KAAY,OAAO,GACjB,sBAAsB,GAAG,kBAAkB,GAAG,oBAAoB,GAAG,mBAAmB,GACxF,oBAAoB,GAAG,oBAAoB,GAAG,kBAAkB,GAAG,mBAAmB,GACtF,uBAAuB,CAAC;IAE1B;;OAEG;IACH,UAAiB,KAAK,CAAC,CAAC,GAAG,GAAG;QAC5B,qFAAqF;QACrF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,iFAAiF;QACjF,EAAE,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,CAAC,CAAC;QACjC,iDAAiD;QACjD,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;KAChE;CACF;AAyPD;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,EAAE,SAAS,QAAQ,CAAC,KAAK,EAqB9C,CAAC;AAKF;;;;;;;;;GASG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,QAAQ,CAAC,KAAK,GAAG,IAAI,CAKtE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,SAAS,GAAG,IAAI,EAC1B,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,QAAQ,CAAC,OAAO,GACzB,OAAO,CAAC,MAAM,CAAC,CAwBjB"}

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

@@ -0,0 +1,23 @@
+import { ICell } from '@sheetxl/sdk';
+import { AppendDependencyOptions } from './appendSections';
+/**
+ * Renders a cell's report: value, formula, spans, spill, the effective style, and its position in
+ * the dependency graph.
+ *
+ * @remarks
+ * 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.
+ *
+ * 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.
+ */
+export declare function renderCell(cell: ICell, options?: AppendDependencyOptions): string;
+//# sourceMappingURL=renderCell.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"renderCell.d.ts","sourceRoot":"","sources":["../../../../src/markdown/renderCell.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAU,MAAM,cAAc,CAAC;AAGlD,OAAO,EAAyC,KAAK,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAMvG;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,KAAK,EACX,OAAO,CAAC,EAAE,uBAAuB,GAChC,MAAM,CAqBR"}

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

@@ -0,0 +1,61 @@
+import { ICellRange } from '@sheetxl/sdk';
+import { CellEncoding } from '../encode';
+import { AppendDependencyOptions, AppendFeatureOptions } from './appendSections';
+import { ProfileRegionOptions } from './profileRegion';
+/**
+ * Options for {@link renderCellRange}.
+ */
+export interface RenderCellRangeOptions extends AppendFeatureOptions, AppendDependencyOptions, ProfileRegionOptions {
+    /**
+     * How much formatting cell text carries.
+     *
+     * @defaultValue {@link CellEncoding.Mode.Display}
+     */
+    mode?: CellEncoding.Mode;
+    /**
+     * Cap on rendered data cells; the report notes truncation when exceeded.
+     *
+     * @defaultValue 1000
+     */
+    maxCells?: number;
+    /**
+     * Compute and print the `Profile` section — per-series counts, types and aggregates.
+     *
+     * @defaultValue true
+     *
+     * @remarks
+     * On by default here, unlike `AppendFeatureOptions.profile` (off by default for a sheet report's
+     * `Contentful` section): a sheet report is scanning every block on the caller's behalf, while
+     * this range was named directly, so the same budget reasoning argues the other way. Set `false`
+     * to skip the scan — e.g. a caller only after the raw values, or one already holding a `getStats()`
+     * result of its own.
+     */
+    profile?: boolean;
+}
+/**
+ * Renders a markdown report of a cell range: its values as a table, plus the profile, counts,
+ * formulas, spills, intersecting sheet objects and the rules over it — all confined to the range.
+ *
+ * @remarks
+ * **This is where the values live.** A sheet report says *where* the blocks are; this reads one.
+ * Values belong at this altitude and not the one above precisely because the caller named the
+ * bounds — a sheet has no bound but its size.
+ *
+ * **It is also where the stats live, by default.** The same per-series counts, types and
+ * aggregates a `Contentful` region's profile computes are computed here directly over the named
+ * range — see {@link appendProfile} — so reading a range and understanding its shape is one call,
+ * not a values read followed by a separate `getStats()`.
+ *
+ * **It does not repeat the feature partitions.** A sheet report is already that map over the
+ * whole used range, so listing them again inside a rectangle carved out of it says the same
+ * thing twice at a narrower scope. The one who wants a partition of this range asks for it —
+ * `getRegions` on the range is the call, and it is one expression.
+ *
+ * `ICellRange` is the *live handle*: it knows its sheet, so its report carries A1 addresses,
+ * hidden headers and intersecting tables. {@link renderValues} covers `IRange` and `Scalar[][]`,
+ * which know none of that.
+ *
+ * Cell text goes through {@link encodeCell}, so whatever a report prints, grep can find.
+ */
+export declare function renderCellRange(range: ICellRange, options?: RenderCellRangeOptions): string;
+//# sourceMappingURL=renderCellRange.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"renderCellRange.d.ts","sourceRoot":"","sources":["../../../../src/markdown/renderCellRange.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAc,MAAM,cAAc,CAAC;AAEtD,OAAO,EAAE,YAAY,EAAc,MAAM,WAAW,CAAC;AACrD,OAAO,EAEoB,KAAK,uBAAuB,EAAE,KAAK,oBAAoB,EACjF,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAiB,KAAK,oBAAoB,EAAsB,MAAM,iBAAiB,CAAC;AAG/F;;GAEG;AACH,MAAM,WAAW,sBAAuB,SAAQ,oBAAoB,EAAE,uBAAuB,EAAE,oBAAoB;IACjH;;;;OAIG;IACH,IAAI,CAAC,EAAE,YAAY,CAAC,IAAI,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,UAAU,EACjB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,MAAM,CAyCR"}

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

@@ -0,0 +1,15 @@
+import { IConditionalFormat } from '@sheetxl/sdk';
+/**
+ * Renders one conditional format's report — where it applies, what it tests, and what it paints.
+ *
+ * @remarks
+ * The rule as AUTHORED. What a rule does to a particular cell is a cell report's question and is
+ * already answered there (`ICell.getStyle()` is the rendered style, conditional formatting folded
+ * in); what a cell can never show is the predicate, which is this report's whole subject.
+ *
+ * The listings — a region row, the `Conditional Formats` section — carry the same rule on one line
+ * through the same describers. This adds only what does not fit there: the anchor in full and the
+ * evaluation order.
+ */
+export declare function renderConditionalFormat(format: IConditionalFormat): string;
+//# sourceMappingURL=renderConditionalFormat.d.ts.map

package/types/src/markdown/renderConditionalFormat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderConditionalFormat.d.ts","sourceRoot":"","sources":["../../../../src/markdown/renderConditionalFormat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAMvD;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CA2B1E"}

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

@@ -0,0 +1,11 @@
+import { ICellRange } from '@sheetxl/sdk';
+/**
+ * Renders a counts report — per-feature cell occupancy.
+ *
+ * @remarks
+ * `getCounts` answers "how much of each feature is here"; stats answers "what are the values
+ * like". Zero features are elided — the record's stable full-key shape is an API property, not
+ * a reporting one; a report of twenty zeros buries the four numbers that matter.
+ */
+export declare function renderCounts(counts: ICellRange.Counts): string;
+//# sourceMappingURL=renderCounts.d.ts.map

package/types/src/markdown/renderCounts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderCounts.d.ts","sourceRoot":"","sources":["../../../../src/markdown/renderCounts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAI/C;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,GAAG,MAAM,CAc9D"}

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

@@ -0,0 +1,15 @@
+import { IDataValidation } from '@sheetxl/sdk';
+/**
+ * Renders one data validation's report — where it applies, what it permits, and what a reader is
+ * told when it does not.
+ *
+ * @remarks
+ * A validation is a **precondition on writing**, which is why an agent reads one: it is the
+ * difference between a value that will be accepted and one that will be refused, and the list of
+ * allowed values is very often the only place a sheet states its own vocabulary.
+ *
+ * The prompt and alert text are on this report and not in any listing, because they are prose —
+ * and because the alert text is frequently where the author explained the rule in words.
+ */
+export declare function renderDataValidation(validation: IDataValidation): string;
+//# sourceMappingURL=renderDataValidation.d.ts.map

package/types/src/markdown/renderDataValidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderDataValidation.d.ts","sourceRoot":"","sources":["../../../../src/markdown/renderDataValidation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAM/C;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,eAAe,GAAG,MAAM,CAsCxE"}

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

@@ -0,0 +1,63 @@
+import { ICalculation, ISheet } from '@sheetxl/sdk';
+/**
+ * Options for {@link renderFormula}.
+ */
+export interface RenderFormulaOptions {
+    /**
+     * Cap on listed tokens; the report notes truncation when exceeded.
+     *
+     * @defaultValue 200
+     */
+    maxTokens?: number;
+    /**
+     * The sheet an identifier is resolved against.
+     *
+     * @defaultValue the sheet owning the formula's first reference
+     *
+     * @remarks
+     * Names, tables and functions are all scoped, so resolving one requires knowing *where the
+     * formula lives* — which `ICalculation.IFormula` does not carry. It is normally recoverable
+     * 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;
+}
+/**
+ * Renders a formula's *analysis* report: its text, calculation status, behavioral flags, the
+ * identifiers it names, the ranges it references, and its token stream.
+ *
+ * @remarks
+ * **Analysis, not state.** A cell report answers "what is here" — value, format, memberships.
+ * This answers "what does this expression do", which is a different question with a different
+ * shape, and is why `formula` is its own kind rather than a section of `cell`.
+ *
+ * **It computes.** `evaluate()` is asynchronous by contract, which is why this report went without
+ * a value for as long as it did — but "what does `=SUM(H14:H25)` come to" is the most common
+ * question anyone brings to a formula, and answering it with a token stream sent the reader off to
+ * make a second call for the number they already asked for. One `await` buys the whole difference,
+ * and calculation has already settled by the time a renderer runs (see `renderMarkdown`).
+ *
+ * The flags are printed only when true. `isValid` is the exception, printed only when *false*:
+ * a formula that failed to parse is the finding, and a parse failure is not the same as an
+ * error result — `=1/0` parses fine and evaluates to `#DIV/0!`.
+ *
+ * **Symbols resolve themselves.** An agent reading `=SUM(Revenue)` cannot act until it knows
+ * whether `Revenue` is a defined name, a table column or a header string — three different
+ * objects with three different next calls, and the text alone does not say which. The section
+ * names each one and what it points at, which also makes the two silent failures loud: a name
+ * that no longer resolves, and a function that does not exist (the `#NAME?` an agent would
+ * otherwise diagnose from the value). `Symbols`, not `Identifiers`: the skills teach the names
+ * roster as "the symbol table", so this is the per-formula slice of a concept the reader already
+ * has, under the word they have for it.
+ *
+ * Cell references stay in `References` rather than joining it — an address is self-describing,
+ * and that listing is *indexed* because the index is the argument to `setReferenceAt`.
+ *
+ * **A DEFINED NAME renders through here too**, because a name IS a formula plus an identity — the
+ * SDK models it that way (`INamedFormula extends IFormula, INamed`) and so does this report. It
+ * gains an identity header and a `Dependents` section; everything else is the same analysis,
+ * because the questions are the same ones. A separate renderer would have had to answer them
+ * twice.
+ */
+export declare function renderFormula(formula: ICalculation.IFormula, options?: RenderFormulaOptions): Promise<string>;
+//# sourceMappingURL=renderFormula.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"renderFormula.d.ts","sourceRoot":"","sources":["../../../../src/markdown/renderFormula.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAsB,MAAM,EAAU,MAAM,cAAc,CAAC;AAMrF;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA6PD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,YAAY,CAAC,QAAQ,EAC9B,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,MAAM,CAAC,CA8GjB"}