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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sheetxl/query",
   "description": "SheetXL - Workbook read surface and renderers (grep, reports) — capabilities declared once, adapted by any host surface",
-  "version": "0.8.0-beta.1",
+  "version": "0.8.0-beta.11",
   "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.8.0-beta.1",
-    "@sheetxl/sdk": "^0.8.0-beta.1"
+    "@sheetxl/primitives": "^0.8.0-beta.11",
+    "@sheetxl/sdk": "^0.8.0-beta.11"
   },
   "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/_aliases.d.ts

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

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

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

package/types/src/api/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,171 @@
+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 `IWorksheetCollection`, and
+     * `ICellRange.setStyle` that a range's style is reached through `getStyle()`. A bare search for
+     * `add` or `setStyle` lists every type that has one and leaves the claim standing.
+     */
+    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;
+/**
+ * A compiler finding without its `Did you mean '…'?` when TypeScript means a member the index does
+ * not offer — a deprecated alias is still declared, so the compiler finds it nearest.
+ *
+ * @param message A compiler finding, e.g. `Property 'setFormat' does not exist on type 'ICellRange'.
+ * Did you mean 'getFormat'?`
+ */
+export declare function withoutHiddenSuggestion(index: ScriptingApi.Index, message: string): string;
+/**
+ * The members nearest a name the script used and the API does not have — the answer an `api`
+ * lookup would be asked for next, inline.
+ *
+ * @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/delta/describeDelta.d.ts

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

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

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

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

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

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

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

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

@@ -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,14 +35,26 @@ 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";
+        /**
+         * The formula text where the cell has a formula (`=SUM(B2:B9)`), else its stored
+         * {@link Mode.Value | value}.
+         *
+         * @remarks
+         * Excel's Show Formulas view: for reading a block's logic as a grid. The inputs read as the
+         * scalars the formulas compute with — `0.25`, not `25%`; a date as its serial. The text carries
+         * its leading `=`, as the formula bar shows it.
+         */
+        readonly Formula: "formula";
     };
     type Mode = typeof Mode[keyof typeof Mode];
     /**
@@ -137,8 +149,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.