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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sheetxl/query",
   "description": "SheetXL - Workbook read surface and renderers (grep, reports) — capabilities declared once, adapted by any host surface",
-  "version": "0.7.28-beta.4",
+  "version": "0.8.0-beta.10",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {
@@ -9,13 +9,12 @@
       "types": "./types/index.d.ts",
       "browser": "./browser/esm/index.mjs",
       "node": "./node/esm/index.mjs",
-      "import": "./browser/esm/index.mjs",
-      "require": "./browser/cjs/index.cjs"
+      "default": "./browser/esm/index.mjs"
     }
   },
   "types": "./types/index.d.ts",
   "module": "./browser/esm/index.mjs",
-  "main": "./browser/cjs/index.cjs",
+  "main": "./browser/esm/index.mjs",
   "sideEffects": false,
   "engines": {
     "node": ">=20 <21 || >=22"
@@ -43,10 +42,10 @@
     "query"
   ],
   "dependencies": {
-    "@sheetxl/primitives": "^0.7.28-beta.4",
-    "@sheetxl/sdk": "^0.7.28-beta.4"
+    "@sheetxl/primitives": "^0.8.0-beta.10",
+    "@sheetxl/sdk": "^0.8.0-beta.10"
   },
   "devDependencies": {
-    "@types/node": "^26.1.2"
+    "@types/node": "^26.6.4"
   }
 }

package/types/src/Tool.d.ts

@@ -104,5 +104,43 @@ export declare namespace Tool {
          */
         render(result: R): string | Promise<string>;
     }
+    /**
+     * A capability that reads the INSTALL rather than a workbook — the API reference.
+     *
+     * @remarks
+     * A separate shape rather than a {@link Descriptor} with an ignored argument, because what a
+     * surface wraps around a descriptor is exactly the part that does not apply: naming a workbook on
+     * a terminal, routing to a session over MCP. A reference answers the same with no workbook open
+     * and no session created, and a surface that demanded either would be asking for something the
+     * capability never reads.
+     *
+     * Everything else holds as it does for a descriptor: defined once, adapted mechanically, text
+     * agent-facing and English, defaults applied by the tool.
+     */
+    interface Reference<A = any, R = any> {
+        /** Tool name and subcommand — the same word on every surface. */
+        readonly name: string;
+        /** One or two lines, agent-facing, English. */
+        readonly description: string;
+        readonly params: readonly Param[];
+        run(args: A): Promise<R>;
+        /** The default agent-facing rendering of a result. */
+        render(result: R, options?: RenderOptions): string;
+    }
+    /**
+     * What a surface tells a renderer about itself.
+     */
+    interface RenderOptions {
+        /**
+         * How THIS surface spells the capability's own command — `sheetxl api`, `.api`. Defaults to the
+         * bare name, which is the spelling of a tool call.
+         *
+         * @remarks
+         * An answer that points at a follow-up ("everything on the type: …") is printing something to
+         * be typed, and the same capability is typed differently on each surface. This is the one
+         * affordance a renderer cannot work out for itself.
+         */
+        readonly command?: string;
+    }
 }
 //# sourceMappingURL=Tool.d.ts.map

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

@@ -0,0 +1,22 @@
+import { Tool } from '../Tool';
+import { ApiLookup } from './lookupApi';
+export interface ApiArgs {
+    name?: string;
+}
+/**
+ * Looks a name up in the scripting API — see {@link lookupApi} for what a name may be.
+ *
+ * @remarks
+ * A member answer carries its full declaration, sliced out of `scripting.d.ts` by the span the
+ * index recorded. That is the only lookup that reads the declarations at all: a type listing or a
+ * search is answered from the index alone, which is the point of having one.
+ *
+ * Declarations that cannot be read leave the member answer with its index line rather than failing
+ * it; the signature is still the answer to "how do I call this".
+ */
+export declare function describeApi(name?: string): Promise<ApiLookup.Result>;
+/**
+ * The API reference: what a script can call, from the declarations it is type-checked against.
+ */
+export declare const apiTool: Tool.Reference<ApiArgs, ApiLookup.Result>;
+//# sourceMappingURL=apiTool.d.ts.map

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

@@ -0,0 +1,4 @@
+export * from './lookupApi';
+export * from './renderApi';
+export * from './apiTool';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,163 @@
+import { ScriptingApi } from '@sheetxl/sdk';
+/**
+ * What a name resolved to in the scripting API index.
+ *
+ * @remarks
+ * One query string, four answers, decided by what the name matches — the caller never says which
+ * it wants. Nothing → the {@link ApiLookup.Overview}; a type → its members; `Type.member` → that
+ * member in full; anything else → a name {@link ApiLookup.Search}.
+ */
+export declare namespace ApiLookup {
+    /** A type {@link Type} extends, with where to read its members. */
+    interface Base {
+        /** As written in the `extends` clause, type arguments included. */
+        readonly text: string;
+        /** The index key it resolved to, or `null` for a type outside the index (`Iterable`, `Omit`). */
+        readonly key: string | null;
+        readonly memberCount: number;
+    }
+    interface Overview {
+        readonly kind: 'overview';
+        /** How many names the index holds. */
+        readonly total: number;
+        readonly entryPoints: readonly {
+            readonly key: string;
+            readonly entry: ScriptingApi.Entry;
+        }[];
+    }
+    interface Type {
+        readonly kind: 'type';
+        readonly key: string;
+        readonly entry: ScriptingApi.Entry;
+        readonly bases: readonly Base[];
+        /** The member substring the listing was narrowed by, when `Type.<text>` named no exact member. */
+        readonly filter?: string;
+        /** The entry's own members, narrowed by {@link filter} when present. */
+        readonly members: readonly ScriptingApi.Member[];
+    }
+    interface Member {
+        readonly kind: 'member';
+        /** The type that was asked about. */
+        readonly key: string;
+        /** The type that DECLARES the member — a base of {@link key} when the member is inherited. */
+        readonly declaredOn: string;
+        /** Every overload, in declaration order. */
+        readonly members: readonly ScriptingApi.Member[];
+        /**
+         * Each overload's full declaration, documentation included, parallel to {@link members}.
+         * Filled by the caller that has `scripting.d.ts` to slice; a lookup alone leaves it unset.
+         */
+        sources?: readonly string[];
+    }
+    interface Search {
+        readonly kind: 'search';
+        readonly query: string;
+        readonly types: readonly string[];
+        readonly members: readonly {
+            readonly key: string;
+            readonly member: ScriptingApi.Member;
+        }[];
+        /** Matches beyond the caps, not listed. */
+        readonly omitted: number;
+    }
+    /**
+     * `Type.member` where the API has no such thing — the type, the member, or both — answered
+     * with what is nearest rather than with a search for the member's name across every type.
+     *
+     * @remarks
+     * A dotted name is a claim about where something lives, and the claim is what the reader needs
+     * corrected: `ISheets.add` wants to hear that the collection is `ISheetCollection`, and
+     * `ICellRange.setStyle` that a range's style is reached through `getStyle()`. A bare search for
+     * `add` or `setStyle` lists every type that has one and leaves the claim standing.
+     */
+    interface Miss {
+        readonly kind: 'miss';
+        /** The type as typed, and the index key it resolved to — `null` when no type matched. */
+        readonly owner: {
+            readonly text: string;
+            readonly key: string | null;
+        };
+        /** The member as typed. */
+        readonly text: string;
+        /** When the type is unknown: the nearest type names, those with the member first. */
+        readonly nearestTypes: readonly {
+            readonly key: string;
+            readonly hasMember: boolean;
+        }[];
+        /** When the type is known: its members nearest the name, inherited ones included. */
+        readonly nearest: readonly ScriptingApi.Member[];
+        /** Where SheetXL keeps a concept another API spells this way, when the name is one of those. */
+        readonly hints: readonly string[];
+        /** Types that do have a member of exactly this name. */
+        readonly elsewhere: readonly {
+            readonly key: string;
+            readonly member: ScriptingApi.Member;
+        }[];
+        /** `elsewhere` entries beyond the cap, not listed. */
+        readonly elsewhereOmitted: number;
+    }
+    type Result = Overview | Type | Member | Search | Miss;
+}
+/**
+ * The names an overview leads with — where a script's reach into a workbook starts.
+ *
+ * @remarks
+ * Advertising, not scope: every indexed name answers a lookup. These are the handful worth naming
+ * before the reader has asked for anything, in the order a script meets them.
+ */
+export declare const API_ENTRY_POINTS: readonly string[];
+/**
+ * Resolves a name against the scripting API index.
+ *
+ * @param name A type (`ICellRange`), a member (`ICellRange.setValues`), a word to search for, or
+ * nothing for the overview. A leading `SheetXL.` is accepted and ignored — it is how the name is
+ * written in a script, and a name copied out of one should resolve.
+ *
+ * @remarks
+ * `Type.text` is tried as a nested type first (`ICellRange.Coords` is its own entry), then as a
+ * member, inherited ones included. Text that names no member exactly narrows the type's listing to
+ * the members containing it — `ICellRange.merge` answers with every merge-related member rather
+ * than with "not found".
+ */
+export declare function lookupApi(index: ScriptingApi.Index, name?: string): ApiLookup.Result;
+/**
+ * The indexed type of a live SDK object, or `null` when it carries no brand the index knows.
+ *
+ * @remarks
+ * SDK objects answer `true` for an `isI<Name>` brand per interface they implement — the SDK's own
+ * convention for runtime type checks — so the brand names are the type names. An object usually
+ * carries several (a named range is an `INamedRange` AND an `ICellRange`); the most derived one
+ * wins, because its listing reaches the others through `extends` and the reverse is not true.
+ */
+export declare function apiTypeOf(index: ScriptingApi.Index, target: unknown): string | null;
+/**
+ * The `api` lookup that answers a compiler finding — `` `api ICellRanges` lists its members. `` —
+ * or `null` when the finding names no SDK type.
+ *
+ * @param message A TypeScript diagnostic, e.g. `Property 'getValues' does not exist on type 'ICellRanges'.`
+ * @param command How the host spells the lookup — `sheetxl api` in a terminal, `api` for a tool
+ * call. The line is there to be typed, so it has to be typeable where it is shown.
+ *
+ * @remarks
+ * A wrong member is the moment the listing is wanted: the finding names the receiver's type, and
+ * the type is the one thing the lookup needs. Only a plain capitalized name is taken — a union, a
+ * generic or a primitive is not something the index answers for.
+ */
+export declare function apiPointerFor(message: string, command: string): string | null;
+/**
+ * The members nearest a name the script used and the API does not have — the answer an `api`
+ * lookup would be asked for next, inline.
+ *
+ * @param message A compiler finding (`Property 'getFormat' does not exist on type 'ICellRange'.
+ * Did you mean 'getFormula'?`) or a run-time one (`r.getFormat is not a function`).
+ * @param command How the host spells the lookup, as for {@link apiPointerFor}.
+ *
+ * @remarks
+ * A compiler finding names the receiver, so its members are the candidates, TypeScript's own
+ * suggestion first. A run-time one names only the member, so every entry point's members are.
+ * A name another spreadsheet API uses for a concept SheetXL keeps elsewhere is answered with where
+ * (`getFormat` → the style). Returns `null` when nothing is near enough to be worth a line; the
+ * compiler finding's {@link apiPointerFor} still stands then.
+ */
+export declare function apiSuggestionsFor(index: ScriptingApi.Index, message: string, command: string): string | null;
+//# sourceMappingURL=lookupApi.d.ts.map

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

@@ -0,0 +1,13 @@
+import { Tool } from '../Tool';
+import { ApiLookup } from './lookupApi';
+/**
+ * Renders an API lookup as its agent-facing text.
+ *
+ * @remarks
+ * Every answer ends by naming the next lookup, and that line is there to be typed. So it is
+ * written the way the surface showing it spells the command ({@link Tool.RenderOptions.command}):
+ * `sheetxl api ICellRange` in a terminal, `.api ICellRange` in a session. One neutral spelling for
+ * all of them is wrong on most of them — `api IWorkbook` typed into a session is a syntax error.
+ */
+export declare function renderApi(result: ApiLookup.Result, options?: Tool.RenderOptions): string;
+//# sourceMappingURL=renderApi.d.ts.map

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

@@ -15,7 +15,7 @@ import { ICell, Scalar } from '@sheetxl/sdk';
  *
  * ---
  *
- * **Quarantine note.** `ICell.getText()` is the only SDK call this module makes, and it is on its
+ * **Quarantine note.** `ICell.getText()` is the only SDK text call this module makes, and it is on its
  * way out — its contract fuses formatting, localization, csv escaping and this encoding into one
  * method with no clear answer for large values. It is isolated to this file deliberately: when
  * the SDK splits pure number formatting away from the encoding, exactly one file changes and no
@@ -35,12 +35,14 @@ export declare namespace CellEncoding {
          */
         readonly Display: "display";
         /**
-         * The cell as the formula bar shows it — full precision, number formatting stripped.
+         * The stored scalar — what `getValue()` returns, with no number format applied.
          *
          * @remarks
-         * `1234.5678` where {@link Mode.Display | display} shows `$1,234.57`. Dates stay dates
-         * rather than decaying to serials, so the result is still searchable rather than merely
-         * lossless.
+         * `1234.5678` where {@link Mode.Display | display} shows `$1,234.57`, `0.04` where it shows
+         * `4%`, and a date as its serial. A reader wants one of two things: what the grid shows, or
+         * what a formula computes with. There is deliberately no layer in between — the formula
+         * bar's text (`4%` at full precision, dates kept) is the stored scalar restyled by the
+         * format's category, and both of those are already reported.
          */
         readonly Value: "value";
     };
@@ -137,8 +139,8 @@ export declare function encodeCell(cell: ICell, mode: CellEncoding.Mode): CellEn
  * The counterpart to {@link encodeCell} for the stateless value layer (`IRange`, `Scalar[][]`),
  * where there is no cell to ask for text and therefore **no number format to apply**. That is
  * the whole difference: `0.04` encodes as `0.04` here and as `4%` through a cell that formats
- * it. There is consequently no `mode` — the two modes differ only by how much formatting they
- * apply, and here there is none to strip.
+ * it. There is consequently no `mode` — this is what {@link CellEncoding.Mode.Value} produces
+ * for a cell, and the only form a bare value has.
  *
  * Everything above formatting is identical, because it is the same contract: the `'` prefix on
  * strings, `TRUE`/`FALSE`, error labels, blank elision.

package/types/src/grep/GrepTypes.d.ts

@@ -1,5 +1,5 @@
 /**
- * The cell layers `grep` can match against.
+ * The layers `grep` can match against.
  *
  * @remarks
  * These are *not* `ICell.Content`. That enum also carries `formats`, `tables`, `merges` and
@@ -8,19 +8,21 @@
  * The rule, which predicts any future member:
  * **a grep field is a layer whose text was authored by a person or is read by one.**
  *
- * `display`, `value` and `raw` are read; `formula`, `hyperlink` and `numberFormat` are authored.
+ * `display` and `value` are read; `formula`, `hyperlink` and `numberFormat` are authored.
  * A layer that fails the rule fails it because its payload has no canonical text — a fill's
  * "red" may be stored as `FF0000`, a theme slot, or an indexed palette entry, so any pattern
  * against it silently matches less than it claims: a confident wrong answer, which is worse
  * than a missing feature. Color wants *nearness*, not matching — that is selection by
  * attribute, and it belongs to the regions read.
  *
- * Two layers are deliberately absent for the same reason:
- * - `note` — `ICell.Content.Notes` is marked NOT IMPLEMENTED.
- * - `comment` — `IComment.Properties.content` is `any` pending `IRichText.JSON`, so any text
- *   extractor written against it today would quietly miss the shapes it did not anticipate.
+ * The rule does not stop at the cell. A callout, a chart title, a comment and a defined name are
+ * all text a person wrote into the workbook, and none of it is in any cell — so `comment`,
+ * `shape`, `chart` and `name` are layers too, tagged the same way. A search that finds the cell
+ * reading `Fund Size` and misses the callout explaining it has answered a narrower question than
+ * the one asked.
  *
- * Both are additive once the SDK shapes settle.
+ * There is no `note` field: a note is a comment that says so (`IComment.isNote`), and `comment`
+ * searches both.
  */
 export type GrepField = 
 /**
@@ -38,28 +40,18 @@ export type GrepField =
  */
 'display'
 /**
- * The cell as the formula bar shows it — most formatting stripped, **category kept**.
+ * The stored scalar — what `getValue()` returns, with no number format applied.
  *
- * `1234.5678` where {@link GrepField | display} shows `$1,234.57` — but `40%` stays `40%`
- * and dates stay dates, because the formula bar keeps minimal formatting for percents,
- * dates and times (Excel's behavior, faithfully). This is *not* the underlying scalar:
- * a percent cell storing `0.4` reads `40%` here. The stored scalar is
- * {@link GrepField | raw}.
+ * `1234.5678` where {@link GrepField | display} shows `$1,234.57`, `0.4` where it shows `40%`,
+ * dates as serial numbers. This is the layer a cell report's `Value` line and the `IRange` /
+ * stats reads print, so it is the field that makes *those* printed values greppable — the
+ * round-trip that `display` provides for formatted reads. Not a default: serials and
+ * unrounded floats are noise until they are the question.
  *
  * Identical to `display` for every cell whose format only decorates (`General`, plain
- * text) — the default search dedupes that case per cell rather than reporting both.
+ * text) — a search of both dedupes that case per cell rather than reporting it twice.
  */
  | 'value'
-/**
- * The stored scalar, encoded bare — what the stateless value layer prints.
- *
- * `0.4` where {@link GrepField | value} shows `40%`; dates as serial numbers. This is the
- * layer `IRange` / stats reads print (they have no cell to format through), so it is the
- * field that makes *those* printed values greppable — the round-trip that `display`
- * provides for formatted reads. Not a default: serials and unrounded floats are noise
- * until they are the question.
- */
- | 'raw'
 /** Formula text, A1 style (`=SUM(A1:A10)`). Cells without a formula contribute nothing. */
  | 'formula'
 /** Hyperlink target — the address, not the display text (which is already `display`). */
@@ -72,14 +64,48 @@ export type GrepField =
  * cells are percentages" — the rendered `40%` is not. Matches cells with a *direct*
  * format, including value-less ones (a formatted-but-empty column is a real finding).
  */
- | 'numberFormat';
+ | 'numberFormat'
+/**
+ * The comment or note on a cell, and every reply in its thread — each its own row.
+ *
+ * A cell layer like the others: the match is the commented cell, and a cell that matches in
+ * its display AND its comment is one cell. A comment on an empty cell is still found.
+ */
+ | 'comment'
+/**
+ * The text written on a shape — a text box, a callout — and its alt text.
+ *
+ * The match is the shape, addressed by the cells it is anchored over (`F2:H6`), which is what
+ * `range.getMovables()` takes to get back to it.
+ */
+ | 'shape'
+/**
+ * What a chart says in words: its title, its axis titles, the series names written into it,
+ * and its alt text. Addressed like a {@link GrepField | shape}.
+ *
+ * A series named by a cell (`=Sales!$C$3`) is not repeated here — that text is the cell's, and
+ * `display` already finds it there.
+ */
+ | 'chart'
+/**
+ * Defined names and tables: the name, what it refers to (`=Summary!$B$4`, `=0.21`) and its
+ * comment.
+ *
+ * The match is the name, spelled as a formula writes it (`'EU Ops'!Rate` when sheet-scoped) —
+ * a name has no cell of its own. Under a {@link GrepArgs.scope | scope} a name is searched
+ * when it is scoped to a searched sheet or designates cells inside the searched range.
+ */
+ | 'name';
 export declare const GrepField: {
     readonly Display: "display";
     readonly Value: "value";
-    readonly Raw: "raw";
     readonly Formula: "formula";
     readonly Hyperlink: "hyperlink";
     readonly NumberFormat: "numberFormat";
+    readonly Comment: "comment";
+    readonly Shape: "shape";
+    readonly Chart: "chart";
+    readonly Name: "name";
 };
 /** Every field, in the order they are searched and reported. */
 export declare const GREP_FIELDS: readonly GrepField[];
@@ -87,12 +113,15 @@ export declare const GREP_FIELDS: readonly GrepField[];
  * The default field set.
  *
  * @remarks
- * What you can see, what the formula bar shows, and what is structurally behind both.
- * `value` is a default *because* the search dedupes it: for the majority of cells it is
- * byte-identical to `display` and is suppressed per cell, so it only surfaces where it
- * carries new information — `1234.5678` behind `$1,234.57`. A duplicate hit costs an agent
- * a second look for no new information; a missing layer costs a silent zero-hit miss on
- * full-precision searches, which is worse.
+ * What you can see and what is structurally behind it. `value` is opt-in: a search is almost
+ * always for text as the grid shows it, and the stored scalar in a default search makes every
+ * numeric pattern hit date serials and unrounded floats nobody was looking at. The search that
+ * wants it — a full-precision number copied from a stats read or a cell report's `Value` line —
+ * knows it does, and asks with `fields: ['value']`.
+ *
+ * The layers off the grid are defaults. A caller who has to ask for `shape` already knows the
+ * callout is there; the search that needs it is the one that does not. They cost one pass over a
+ * sheet's objects, not over its cells.
  */
 export declare const GREP_FIELDS_DEFAULT: readonly GrepField[];
 /** What a grep result should carry. */
@@ -134,9 +163,10 @@ export interface GrepArgs {
      */
     pattern: string;
     /**
-     * Which cell layers to search.
+     * Which layers to search.
      *
-     * @defaultValue {@link GREP_FIELDS_DEFAULT} — `['display', 'value', 'formula']`
+     * @defaultValue {@link GREP_FIELDS_DEFAULT} —
+     * `['display', 'formula', 'comment', 'shape', 'chart', 'name']`
      */
     fields?: readonly GrepField[];
     /**
@@ -166,11 +196,11 @@ export interface GrepArgs {
      */
     word?: boolean;
     /**
-     * Invert the match — report cells where **no** requested field matched (`rg -v`).
+     * Invert the match — report cells and objects where **no** requested field matched (`rg -v`).
      *
      * @remarks
-     * Scoped to cells grep visits: a cell must have text in at least one requested field to be
-     * reported (an empty cell is not a finding, and "every blank cell" is not an answer).
+     * Scoped to what grep visits: a cell or object must have text in at least one requested field
+     * to be reported (an empty cell is not a finding, and "every blank cell" is not an answer).
      * Reported rows carry the first requested field that has text, as the evidence line.
      */
     invert?: boolean;
@@ -200,14 +230,16 @@ export interface GrepArgs {
      */
     hidden?: boolean;
     /**
-     * Stop after this many matching cells. Truncation is always reported, never silent.
+     * Stop after this many matches — cells and objects together. Truncation is always reported,
+     * never silent.
      *
      * @defaultValue 200 — a grep result returns into a context window, not a terminal stream,
      * so unbounded output is a cost the caller did not ask for. `0` removes the cap.
      *
      * @remarks
-     * Counts **cells**, not match rows — a cell matching in two fields is one unit of budget.
-     * The search looks one cell past the cap, so a result that ends exactly at `maxCount` is
+     * Counts **cells and objects**, not match rows — a cell matching in two fields is one unit of
+     * budget, and so is a chart matching in its title and an axis.
+     * The search looks one match past the cap, so a result that ends exactly at `maxCount` is
      * only reported truncated when a further match actually exists.
      */
     maxCount?: number;
@@ -240,6 +272,10 @@ export interface GrepMatchContext {
  * order.
  *
  * @remarks
+ * Text that is not in a cell keeps the same shape. A shape or a chart is an entry per matched
+ * text, addressed by the cells it is anchored over, after its sheet's cells; a defined name is an
+ * entry addressed by the name itself, after every sheet.
+ *
  * Deliberately not coalesced into blocks: uniform runs of identical values are *regions* — a
  * payload feature splits where the value changes, so the regions read already owns that shape,
  * in 2-D and with the full partition to rank against. Grep answering cell-grain and regions
@@ -248,9 +284,15 @@ export interface GrepMatchContext {
  * renderer merely groups by it.
  */
 export interface GrepMatch {
-    /** Sheet name. */
+    /**
+     * Sheet name — for a `name` match, the sheet the name is scoped to, or `''` for a
+     * workbook-scoped one.
+     */
     sheet: string;
-    /** A1 cell address within the sheet. */
+    /**
+     * A1 cell address within the sheet; the anchor range (`F2:H6`) for a shape or chart; the name
+     * itself for a defined name. Qualified with `sheet`, each is something a follow-up call takes.
+     */
     address: string;
     /**
      * Which layer matched.
@@ -272,6 +314,8 @@ export interface GrepSheetMatches {
     sheet: string;
     /** Distinct cells that produced at least one match in this sheet. */
     cells: number;
+    /** Shapes and charts on this sheet that produced at least one match. */
+    objects: number;
 }
 /** The result of a {@link grep}. */
 export interface GrepResult {
@@ -283,6 +327,8 @@ export interface GrepResult {
     matches: readonly GrepMatch[];
     /** Distinct cells that produced at least one match. */
     cellCount: number;
+    /** Shapes, charts and names that produced at least one match. */
+    objectCount: number;
     /** Per-sheet counts, in search order — only sheets with at least one match appear. */
     sheets: readonly GrepSheetMatches[];
     /**

package/types/src/grep/grep.d.ts

@@ -1,9 +1,12 @@
 import { IWorkbook } from '@sheetxl/sdk';
 import { GrepArgs, GrepResult } from './GrepTypes';
 /**
- * Searches a workbook's cell contents by pattern.
+ * Searches a workbook's text by pattern — its cells, and what is written off the grid.
  *
  * @remarks
+ * Per sheet: the cells in reading order (a comment rides its cell), then the shapes and charts
+ * in reading order of their anchors. Defined names follow every sheet, since they belong to none.
+ *
  * Deliberately shaped after ripgrep — args, defaults and vocabulary are pretrained, and every
  * novel idiom is paid for in error loops.
  *

package/types/src/index.d.ts

@@ -2,6 +2,7 @@ import { Tool } from './Tool';
 export * from './Tool';
 export * from './encode';
 export * from './grep';
+export * from './api';
 export * from './markdown';
 /**
  * The read surface, defined once.
@@ -17,4 +18,12 @@ export * from './markdown';
  * reason). A capability joins this list only when it is not a one-line run idiom.
  */
 export declare const TOOLS: readonly Tool.Descriptor[];
+/**
+ * The reference surface — capabilities that read the install rather than a workbook.
+ *
+ * @remarks
+ * Registered by every host surface exactly as {@link TOOLS} is, minus the part that names a
+ * workbook. See {@link Tool.Reference}.
+ */
+export declare const REFERENCES: readonly Tool.Reference[];
 //# sourceMappingURL=index.d.ts.map