The workbook read surface — capabilities declared once, as descriptors any surface adapts mechanically. Designed so an agent can use it well; built for anyone.
@sheetxl/sdk engine + analysis → typed results
↓
@sheetxl/query capabilities + renderers ← this package
↓
host surfaces command flags · tool schemas · embedding hosts
| Capabilities | grep — search cell contents by pattern across a workbook |
| The value encoding | the ' string prefix, TRUE/FALSE, error literals — the presentation contract every read shares |
| Renderers | typed result → the aligned listing or table a reader consumes |
IWorkbook. A host may hold a workbook with
unsaved edits and no file behind it — a path-shaped entry point would exclude that host or
make it read stale data. Loading belongs to the caller.A capability is declared once, as a Tool.Descriptor, and each surface generates its own
registration from it:
import { TOOLS } from '@sheetxl/query';
for (const descriptor of TOOLS) {
// a flag parser: descriptor.params → options
// a tool registry: descriptor.params → inputSchema
}
Adding a capability here adds it to every surface with no edit in any of them. Affordances — how you name a workbook, how a result reaches its reader — are expected to differ and stay with the surface that owns them. The divergence worth preventing is two hand-written copies of one capability.
Portability is the defining property of a macro, and the SDK is the portability boundary. A
macro that imported @sheetxl/query would work in one host and fail in another — an
environment-dependent cliff that passes every test you would think to write. A macro returns
data; the layer above renders it.