@snaptrude/plugin-core 0.3.0 → 0.6.0

package/dist/api/program/spreadsheet.d.ts

@@ -0,0 +1,2041 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../types";
+/**
+ * Program spreadsheet — read a building's program/takeoff data and render, build,
+ * and export report sheets from it. The surface spans two levels:
+ *
+ * - **High-level renders** — {@linkcode PluginProgramSpreadsheetApi.render} (rows +
+ *   columns → a formatted, titled table) and its dataset specializations
+ *   {@linkcode PluginProgramSpreadsheetApi.renderTakeoff} /
+ *   {@linkcode PluginProgramSpreadsheetApi.renderProgram} (the host pulls the
+ *   dataset). Authors think "render my takeoff to a sheet".
+ * - **Low-level construction** — for authors who need fine control:
+ *   {@linkcode PluginProgramSpreadsheetApi.createSheet},
+ *   {@linkcode PluginProgramSpreadsheetApi.setValues},
+ *   {@linkcode PluginProgramSpreadsheetApi.setFormulas},
+ *   {@linkcode PluginProgramSpreadsheetApi.setStyles},
+ *   {@linkcode PluginProgramSpreadsheetApi.mergeCells},
+ *   {@linkcode PluginProgramSpreadsheetApi.addConditionalFormatting},
+ *   {@linkcode PluginProgramSpreadsheetApi.recalculate}, and
+ *   {@linkcode PluginProgramSpreadsheetApi.transaction} (atomic, undoable batch).
+ *
+ * Plus dataset reads ({@linkcode PluginProgramSpreadsheetApi.getProgram} /
+ * {@linkcode PluginProgramSpreadsheetApi.getTakeoff} — the data the render* methods
+ * draw), sheet reads ({@linkcode PluginProgramSpreadsheetApi.listSheets} /
+ * {@linkcode PluginProgramSpreadsheetApi.getSheetData}), charts + emphasis
+ * ({@linkcode PluginProgramSpreadsheetApi.addChart} /
+ * {@linkcode PluginProgramSpreadsheetApi.highlightCells}), workbook file export
+ * ({@linkcode PluginProgramSpreadsheetApi.export}), reusable
+ * {@linkcode PluginProgramSpreadsheetApi.templates}, live
+ * {@linkcode PluginProgramSpreadsheetApi.bindings}, a sandboxed script escape hatch
+ * ({@linkcode PluginProgramSpreadsheetApi.runScript}), an audit log
+ * ({@linkcode PluginProgramSpreadsheetApi.getAuditLog}), and a liveness
+ * {@linkcode PluginProgramSpreadsheetApi.ping}. `addTable` is intentionally not
+ * exposed — `render` composes header + rows + table in one call.
+ *
+ * **Verb note (naming authority; rows pending merge into constitution §4 by its owner).**
+ * Existing §4 verbs used as-is: `get`, `list`, `set` (bulk cell/format writes;
+ * read back via {@linkcode PluginProgramSpreadsheetApi.getSheetData}), `create`,
+ * `add` (charts, conditional formats), `apply` (templates), `export`, and
+ * `transaction` (the sanctioned atomic-batch verb), plus the ratified `render` and
+ * `highlight` program domain verbs ◆. New program-domain verbs ratified here ◆:
+ * `recalculate` (recompute the workbook's formula results — distinct from
+ * `refresh`), `merge` ({@linkcode PluginProgramSpreadsheetApi.mergeCells} spans a
+ * cell range — a spreadsheet-domain verb, explicitly NOT the CSG-solid `union`
+ * fold), `refresh` ({@linkcode PluginProgramSpreadsheetBindingsApi.refresh}
+ * re-pulls a binding's live source — distinct from `recalculate`), `run`
+ * ({@linkcode PluginProgramSpreadsheetApi.runScript} executes a sandboxed script),
+ * and `ping` (a meta liveness probe). Renames for compliance: the host's `save` →
+ * `templates.create`; `getRecentEntries` → `getAuditLog`.
+ *
+ * Accessed via `snaptrude.program.spreadsheet`.
+ */
+export declare abstract class PluginProgramSpreadsheetApi {
+    constructor();
+    /**
+     * Reusable sheet templates — capture a sheet's layout as a named template and
+     * re-apply it to another sheet. See {@linkcode PluginProgramSpreadsheetTemplatesApi}.
+     */
+    abstract templates: PluginProgramSpreadsheetTemplatesApi;
+    /**
+     * Live data bindings — bind a program dataset to a sheet range and refresh it
+     * on demand. See {@linkcode PluginProgramSpreadsheetBindingsApi}.
+     */
+    abstract bindings: PluginProgramSpreadsheetBindingsApi;
+    /**
+     * Render a titled, formatted table onto a named sheet (create-or-replace).
+     *
+     * The intent-level replacement for the raw cell-write sequence: it writes the
+     * header + rows, applies per-column format/alignment, optionally wraps the
+     * block in a table, freezes the header, and appends a totals row. This is the
+     * generic table render; the `render*` family is reserved to also carry
+     * dataset-specific renders (`renderTakeoff`, `renderProgram`) once their
+     * argument shapes are ratified.
+     *
+     * @param sheetName - Target sheet name.
+     * @param columns - Column definitions, at least one (see
+     *   {@linkcode PluginSpreadsheetColumn}).
+     * @param rows - Row objects keyed by column `key`.
+     * @param options - Optional `title`, `startCell` (default `"A1"`), `whenExists`
+     *   (default `"replace"`), `asTable` (default `true`), `freezeHeader` (default
+     *   `true`), and `totals` row.
+     * @returns A {@linkcode PluginProgramSpreadsheetRenderResult} with the written
+     *   ranges and counts.
+     * @throws If `columns` is empty, the target sheet exists and `whenExists` is
+     *   `"error"`, or a cell address is invalid.
+     *
+     * @examplePrompt Render my takeoff as a table on a sheet
+     * @examplePrompt Write the area schedule to a spreadsheet with totals
+     * @examplePrompt Put the department breakdown on a sheet called "Program"
+     * @examplePrompt Output this data as a formatted table with a header
+     * @examplePrompt Create a report sheet from these rows and columns
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.program.spreadsheet.render(
+     *   "Program",
+     *   [
+     *     { key: "name", header: "Department" },
+     *     { key: "area", header: "Area", format: "0.00", align: "right" },
+     *   ],
+     *   [{ name: "FOH", area: 120.5 }],
+     *   { totals: [{ column: "area", fn: "sum", label: "Total" }] },
+     * )
+     * ```
+     */
+    abstract render(sheetName: string, columns: PluginSpreadsheetColumn[], rows: Record<string, PluginSpreadsheetCell>[], options?: {
+        title?: string;
+        startCell?: string;
+        whenExists?: "replace" | "error";
+        asTable?: boolean;
+        freezeHeader?: boolean;
+        totals?: PluginSpreadsheetTotal[];
+    }): PluginApiReturn<PluginProgramSpreadsheetRenderResult>;
+    /**
+     * Render the quantity/material takeoff onto a sheet.
+     *
+     * A specialization of the render* family: the **host pulls and projects the
+     * current takeoff dataset itself** — the plugin supplies only the target
+     * `sheetName`, an optional `title`, and an optional `filter`; there is **no
+     * data argument**. Returns the same rendered-artifact record as
+     * {@linkcode PluginProgramSpreadsheetApi.render}.
+     * _(Authored ahead — optional via the `spreadsheet?` mount until the host
+     * round-trip is live.)_
+     *
+     * @param options - Optional `sheetName`, `title`, and `filter` (a
+     *   {@linkcode PluginProgramSpreadsheetRenderDatasetArgs}).
+     * @returns A {@linkcode PluginProgramSpreadsheetRenderResult} with the written
+     *   ranges and counts.
+     * @throws If the takeoff cannot be rendered.
+     *
+     * @examplePrompt Render the takeoff onto a sheet
+     * @examplePrompt Put the quantity takeoff on a spreadsheet
+     * @examplePrompt Generate the takeoff schedule sheet titled Takeoff
+     * @examplePrompt Render the material takeoff filtered to the walls
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.program.spreadsheet.renderTakeoff({ sheetName: "Takeoff" })
+     * ```
+     */
+    abstract renderTakeoff(options?: {
+        sheetName?: string;
+        title?: string;
+        filter?: string;
+    }): PluginApiReturn<PluginProgramSpreadsheetRenderResult>;
+    /**
+     * Render the area program onto a sheet.
+     *
+     * A specialization of the render* family: the **host pulls and projects the
+     * current program dataset itself** (departments with area targets vs allocated)
+     * — the plugin supplies only the target `sheetName`, an optional `title`, and an
+     * optional `filter`; there is **no data argument**. Returns the same
+     * rendered-artifact record as {@linkcode PluginProgramSpreadsheetApi.render}.
+     * _(Authored ahead — optional via the `spreadsheet?` mount until the host
+     * round-trip is live.)_
+     *
+     * @param options - Optional `sheetName`, `title`, and `filter` (a
+     *   {@linkcode PluginProgramSpreadsheetRenderDatasetArgs}).
+     * @returns A {@linkcode PluginProgramSpreadsheetRenderResult} with the written
+     *   ranges and counts.
+     * @throws If the program cannot be rendered.
+     *
+     * @examplePrompt Render the area program onto a sheet
+     * @examplePrompt Put the department program on a spreadsheet
+     * @examplePrompt Generate the program schedule sheet titled Program
+     * @examplePrompt Render the program filtered to the residential departments
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.program.spreadsheet.renderProgram({ sheetName: "Program" })
+     * ```
+     */
+    abstract renderProgram(options?: {
+        sheetName?: string;
+        title?: string;
+        filter?: string;
+    }): PluginApiReturn<PluginProgramSpreadsheetRenderResult>;
+    /**
+     * Export the whole report workbook to a file (xlsx, pdf, or csv).
+     *
+     * Returns the file content as base64 so the plugin can download, upload, or
+     * attach it. This is the workbook **file** export; to read cell **values** back
+     * as data, use {@linkcode PluginProgramSpreadsheetApi.getSheetData} instead.
+     *
+     * @param format - The file format to export the workbook to.
+     * @param options - Optional `fileName` (without extension); a default is used
+     *   when omitted.
+     * @returns A {@linkcode PluginProgramSpreadsheetExportResult} with the file's
+     *   `fileName`, `mimeType`, and base64 `dataBase64`.
+     * @throws If the workbook cannot be serialized to the requested format.
+     *
+     * @examplePrompt Export the report as an Excel file
+     * @examplePrompt Download the whole workbook as a PDF
+     * @examplePrompt Export the program workbook to xlsx
+     * @examplePrompt Save the report as a csv file
+     *
+     * # Example
+     * ```ts
+     * const file = await snaptrude.program.spreadsheet.export("xlsx")
+     * // file.fileName, file.mimeType, file.dataBase64
+     * ```
+     */
+    abstract export(format: PluginSpreadsheetExportFormat, options?: {
+        fileName?: string;
+    }): PluginApiReturn<PluginProgramSpreadsheetExportResult>;
+    /**
+     * List the sheets in the report workbook.
+     *
+     * @returns A {@linkcode PluginProgramSpreadsheetListSheetsResult} with each sheet's
+     *   name/index/visibility/size, plus the active sheet name.
+     *
+     * @examplePrompt List the sheets in the spreadsheet
+     * @examplePrompt What sheets are in the report workbook?
+     * @examplePrompt Which sheet is currently active?
+     * @examplePrompt How many sheets does the report have?
+     *
+     * # Example
+     * ```ts
+     * const { sheets, activeSheet } = await snaptrude.program.spreadsheet.listSheets()
+     * ```
+     */
+    abstract listSheets(): PluginApiReturn<PluginProgramSpreadsheetListSheetsResult>;
+    /**
+     * Read a sheet's data back as a matrix (and optionally as header-keyed records).
+     *
+     * @param sheetName - Sheet to read.
+     * @param options - Optional `range` (A1; omit to read the sheet's used range)
+     *   and `header` (`true` to also get records keyed by the header row).
+     * @returns A {@linkcode PluginProgramSpreadsheetGetSheetDataResult} with the read
+     *   `range`, `values` matrix, and optional `records`.
+     * @throws If the sheet does not exist or the range is invalid.
+     *
+     * @examplePrompt Read the data back from the Program sheet
+     * @examplePrompt Get the values in range A1:D20 of a sheet
+     * @examplePrompt Read a sheet as rows of records keyed by header
+     * @examplePrompt What's in the takeoff sheet right now?
+     *
+     * # Example
+     * ```ts
+     * const { values, records } = await snaptrude.program.spreadsheet.getSheetData(
+     *   "Program",
+     *   { header: true },
+     * )
+     * ```
+     */
+    abstract getSheetData(sheetName: string, options?: {
+        range?: string;
+        header?: boolean;
+    }): PluginApiReturn<PluginProgramSpreadsheetGetSheetDataResult>;
+    /**
+     * Add a chart to a sheet, driven by a cell range.
+     *
+     * @param sheetName - Sheet to add the chart to.
+     * @param chartType - Chart type (see {@linkcode PluginSpreadsheetChartType}).
+     * @param dataRange - A1 range driving the chart.
+     * @param options - Optional `title`, `position` (sheet coords), and `size` (px).
+     * @returns A {@linkcode PluginProgramSpreadsheetAddChartResult} with the new
+     *   chart's id.
+     * @throws If the sheet or data range is invalid.
+     *
+     * @examplePrompt Add a bar chart of the department areas
+     * @examplePrompt Insert a pie chart from range B2:C10
+     * @examplePrompt Put a column chart on the Program sheet
+     * @examplePrompt Chart the area breakdown by department
+     *
+     * # Example
+     * ```ts
+     * const { chartId } = await snaptrude.program.spreadsheet.addChart(
+     *   "Program",
+     *   "column",
+     *   "A1:B10",
+     *   { title: "Area by department" },
+     * )
+     * ```
+     */
+    abstract addChart(sheetName: string, chartType: PluginSpreadsheetChartType, dataRange: string, options?: {
+        title?: string;
+        position?: {
+            x: number;
+            y: number;
+        };
+        size?: {
+            width: number;
+            height: number;
+        };
+    }): PluginApiReturn<PluginProgramSpreadsheetAddChartResult>;
+    /**
+     * Highlight a range of cells (background color and optional emphasis).
+     *
+     * @param sheetName - Sheet containing the range.
+     * @param range - A1 range to highlight.
+     * @param options - Optional `color` (CSS hex; a default emphasis is used when
+     *   omitted) and `bold`.
+     * @returns A {@linkcode PluginProgramSpreadsheetHighlightCellsResult} echoing the
+     *   highlighted sheet and range.
+     * @throws If the sheet or range is invalid.
+     *
+     * @examplePrompt Highlight the cells that are over budget
+     * @examplePrompt Color range A2:A10 red
+     * @examplePrompt Highlight B2:D2 in yellow
+     * @examplePrompt Emphasize the totals row on the Program sheet
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.program.spreadsheet.highlightCells("Program", "A2:A10", {
+     *   color: "#ffe08a",
+     * })
+     * ```
+     */
+    abstract highlightCells(sheetName: string, range: string, options?: {
+        color?: string;
+        bold?: boolean;
+    }): PluginApiReturn<PluginProgramSpreadsheetHighlightCellsResult>;
+    /**
+     * Read the area-program dataset (departments with target vs allocated area).
+     *
+     * Returns the same figures {@linkcode PluginProgramSpreadsheetApi.renderProgram}
+     * projects onto a sheet, as render-ready rows — so a plugin can inspect or
+     * transform the program before rendering it (or render it itself via
+     * {@linkcode PluginProgramSpreadsheetApi.render}). For the canonical
+     * area-program summary read, see {@linkcode PluginProgramMetricsApi.get}.
+     *
+     * @returns A {@linkcode PluginProgramSpreadsheetGetProgramResult} with per-department
+     *   rows (`targetArea`/`allocatedArea`/`variance`), totals, and the report `units`.
+     *
+     * @examplePrompt Get the area program data
+     * @examplePrompt Read the department program before I render it
+     * @examplePrompt Give me the program rows with target vs allocated area
+     * @examplePrompt What's the program dataset the report is built from?
+     *
+     * # Example
+     * ```ts
+     * const program = await snaptrude.program.spreadsheet.getProgram()
+     * for (const row of program.rows) console.log(row.name, row.allocatedArea, row.targetArea)
+     * ```
+     */
+    abstract getProgram(): PluginApiReturn<PluginProgramSpreadsheetGetProgramResult>;
+    /**
+     * Read the quantity/material takeoff dataset (per-element quantities).
+     *
+     * Returns the same rows {@linkcode PluginProgramSpreadsheetApi.renderTakeoff}
+     * projects onto a sheet — one record per counted element (category, item,
+     * level, quantity, unit) — so a plugin can inspect or transform the takeoff
+     * before rendering it (or render it itself via
+     * {@linkcode PluginProgramSpreadsheetApi.render}).
+     *
+     * @returns A {@linkcode PluginProgramSpreadsheetGetTakeoffResult} with the takeoff
+     *   `rows`, a `rowCount`, and the `generatedAt` timestamp.
+     *
+     * @examplePrompt Get the takeoff data
+     * @examplePrompt Read the quantity takeoff rows
+     * @examplePrompt Give me the per-element quantities before I render them
+     * @examplePrompt What's in the material takeoff right now?
+     *
+     * # Example
+     * ```ts
+     * const takeoff = await snaptrude.program.spreadsheet.getTakeoff()
+     * console.log(takeoff.rowCount, "elements")
+     * ```
+     */
+    abstract getTakeoff(): PluginApiReturn<PluginProgramSpreadsheetGetTakeoffResult>;
+    /**
+     * Create (or reuse/replace) a named sheet in the report workbook.
+     *
+     * The blank-canvas complement to {@linkcode PluginProgramSpreadsheetApi.render}:
+     * use it when you want an empty sheet to write into with
+     * {@linkcode PluginProgramSpreadsheetApi.setValues} /
+     * {@linkcode PluginProgramSpreadsheetApi.setFormulas}. By default an existing
+     * sheet of the same name is reused; pass `whenExists` to replace or error.
+     *
+     * @param name - The sheet name to create.
+     * @param whenExists - Behaviour if the name exists: `"reuse"` (default),
+     *   `"replace"`, or `"error"`.
+     * @returns A {@linkcode PluginProgramSpreadsheetCreateSheetResult} with the resolved
+     *   `sheetName`, whether it `replaced` an existing sheet, and its `sheetIndex`.
+     * @throws If the sheet exists and `whenExists` is `"error"`.
+     *
+     * @examplePrompt Create a sheet called Summary
+     * @examplePrompt Add a new blank sheet named Takeoff
+     * @examplePrompt Make a sheet, replacing it if it already exists
+     * @examplePrompt Start a fresh sheet to write into
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.program.spreadsheet.createSheet("Summary")
+     * ```
+     */
+    abstract createSheet(name: string, whenExists?: PluginSpreadsheetWhenExists): PluginApiReturn<PluginProgramSpreadsheetCreateSheetResult>;
+    /**
+     * Write a block of raw values into a sheet, anchored at a cell.
+     *
+     * The low-level cell-write path (the high-level path is
+     * {@linkcode PluginProgramSpreadsheetApi.render}, which adds a header, format,
+     * and totals). Values are written row-major from `startCell` (default `"A1"`);
+     * columns are auto-sized to fit.
+     *
+     * @param sheetName - Sheet to write into.
+     * @param values - Row-major matrix of values to write.
+     * @param startCell - Top-left anchor in A1 notation (default `"A1"`).
+     * @returns A {@linkcode PluginProgramSpreadsheetSetValuesResult} with the written
+     *   `startCell`, `rowCount`, and `colCount`.
+     * @throws If the sheet does not exist or `startCell` is invalid.
+     *
+     * @examplePrompt Write these rows to the sheet starting at A1
+     * @examplePrompt Put this data into the Summary sheet
+     * @examplePrompt Set the values in the takeoff sheet from B2
+     * @examplePrompt Drop this matrix of numbers onto a sheet
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.program.spreadsheet.setValues(
+     *   "Summary",
+     *   [["Department", "Area"], ["FOH", 120.5]],
+     *   "A1",
+     * )
+     * ```
+     */
+    abstract setValues(sheetName: string, values: PluginSpreadsheetCell[][], startCell?: string): PluginApiReturn<PluginProgramSpreadsheetSetValuesResult>;
+    /**
+     * Set formulas on individual cells of a sheet.
+     *
+     * Each entry targets one cell (A1 notation) with a formula expression (a
+     * leading `=` is optional). Pairs with
+     * {@linkcode PluginProgramSpreadsheetApi.recalculate} when you need to force a
+     * recompute.
+     *
+     * @param sheetName - Sheet to set formulas on.
+     * @param formulas - The cell → formula assignments (see
+     *   {@linkcode PluginSpreadsheetFormula}).
+     * @returns A {@linkcode PluginProgramSpreadsheetSetFormulasResult} with the `count`
+     *   of formulas set.
+     * @throws If the sheet does not exist or a cell address is invalid.
+     *
+     * @examplePrompt Put a SUM formula in cell B10
+     * @examplePrompt Set formulas totalling each column
+     * @examplePrompt Add a formula to compute the variance column
+     * @examplePrompt Write =SUM(B2:B9) into B10 on the Summary sheet
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.program.spreadsheet.setFormulas("Summary", [
+     *   { cell: "B10", formula: "=SUM(B2:B9)" },
+     * ])
+     * ```
+     */
+    abstract setFormulas(sheetName: string, formulas: PluginSpreadsheetFormula[]): PluginApiReturn<PluginProgramSpreadsheetSetFormulasResult>;
+    /**
+     * Apply cell styles to one or more ranges of a sheet.
+     *
+     * Sets fill/text color, font, alignment, and number format on each given range.
+     * For a quick single-range emphasis,
+     * {@linkcode PluginProgramSpreadsheetApi.highlightCells} is the shortcut.
+     *
+     * @param sheetName - Sheet containing the ranges.
+     * @param ranges - Range → style assignments (each a range + a
+     *   {@linkcode PluginSpreadsheetCellStyle}).
+     * @returns A {@linkcode PluginProgramSpreadsheetSetStylesResult} with the `count` of
+     *   ranges styled.
+     * @throws If the sheet does not exist or a range is invalid.
+     *
+     * @examplePrompt Make the header row bold with a grey fill
+     * @examplePrompt Right-align the numbers in column B
+     * @examplePrompt Format A1:D1 with a background color and bold text
+     * @examplePrompt Style the totals row
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.program.spreadsheet.setStyles("Summary", [
+     *   { range: "A1:D1", style: { fontWeight: "bold", backColor: "#eef" } },
+     * ])
+     * ```
+     */
+    abstract setStyles(sheetName: string, ranges: PluginSpreadsheetRangeStyle[]): PluginApiReturn<PluginProgramSpreadsheetSetStylesResult>;
+    /**
+     * Merge a contiguous range of cells into a single spanned cell.
+     *
+     * Optionally sets the merged cell's value. (Verb ruling: `merge` is a
+     * spreadsheet-domain verb here — spanning cells — not the CSG-solid `union`.)
+     *
+     * @param sheetName - Sheet containing the range.
+     * @param range - A1 range to merge into one spanned cell.
+     * @param value - Optional value to set in the merged (top-left) cell.
+     * @returns A {@linkcode PluginProgramSpreadsheetMergeCellsResult} echoing the merged
+     *   sheet and range.
+     * @throws If the sheet does not exist or the range is invalid.
+     *
+     * @examplePrompt Merge cells A1 to D1 for the title
+     * @examplePrompt Span the header across the first four columns
+     * @examplePrompt Merge A1:D1 and set it to "Program Summary"
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.program.spreadsheet.mergeCells("Summary", "A1:D1", "Program Summary")
+     * ```
+     */
+    abstract mergeCells(sheetName: string, range: string, value?: PluginSpreadsheetCell): PluginApiReturn<PluginProgramSpreadsheetMergeCellsResult>;
+    /**
+     * Add a conditional-formatting rule to a range.
+     *
+     * Currently supports data-bar rules (a proportional in-cell bar); more rule
+     * types are reserved. For static (non-conditional) emphasis use
+     * {@linkcode PluginProgramSpreadsheetApi.highlightCells} or
+     * {@linkcode PluginProgramSpreadsheetApi.setStyles}.
+     *
+     * @param sheetName - Sheet containing the range.
+     * @param range - A1 range to format.
+     * @param rule - The conditional-format rule (see
+     *   {@linkcode PluginSpreadsheetConditionalRule}).
+     * @returns A {@linkcode PluginProgramSpreadsheetAddConditionalFormattingResult} with
+     *   whether a rule was `created`.
+     * @throws If the sheet does not exist or the range is invalid.
+     *
+     * @examplePrompt Add data bars to the area column
+     * @examplePrompt Show a proportional bar inside cells B2:B10
+     * @examplePrompt Add conditional formatting data bars to the quantities
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.program.spreadsheet.addConditionalFormatting("Summary", "B2:B10", {
+     *   type: "dataBar",
+     *   color: "#4f9cf9",
+     * })
+     * ```
+     */
+    abstract addConditionalFormatting(sheetName: string, range: string, rule: PluginSpreadsheetConditionalRule): PluginApiReturn<PluginProgramSpreadsheetAddConditionalFormattingResult>;
+    /**
+     * Recompute the workbook's formula results.
+     *
+     * Recalculates every formula (or, when `sheetName` is given, focuses that sheet
+     * before recalculating the workbook). (Verb ruling: `recalculate` recomputes
+     * formulas — distinct from {@linkcode PluginProgramSpreadsheetBindingsApi.refresh},
+     * which re-pulls a binding's source data.)
+     *
+     * @param options - Optional `sheetName` to focus before recalculating; omit for
+     *   the whole workbook.
+     * @returns A {@linkcode PluginProgramSpreadsheetRecalculateResult} with the recompute
+     *   `scope` and the focused `sheetName` (or `null`).
+     *
+     * @examplePrompt Recalculate the workbook
+     * @examplePrompt Recompute all the formulas
+     * @examplePrompt Recalculate the Summary sheet
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.program.spreadsheet.recalculate()
+     * ```
+     */
+    abstract recalculate(options?: {
+        sheetName?: string;
+    }): PluginApiReturn<PluginProgramSpreadsheetRecalculateResult>;
+    /**
+     * Run a sequence of sheet operations as one atomic, undoable transaction.
+     *
+     * Batches cell-construction operations (createSheet/setValues/setFormulas/
+     * setStyles/mergeCells) so they commit together and undo as a single step, with
+     * events suspended for speed. (`transaction` is the sanctioned §4 atomic-batch
+     * verb.)
+     *
+     * @param operations - The operations to run in order. Each operation's `args`
+     *   stays that method's schema **object** (the wire shape), not positional.
+     * @param label - Optional undo-history label for the batch.
+     * @returns A {@linkcode PluginProgramSpreadsheetTransactionResult} with the
+     *   `operationCount` and each operation's `results`.
+     * @throws If any operation names an unsupported method or fails.
+     *
+     * @examplePrompt Create a sheet and write to it in one atomic step
+     * @examplePrompt Batch these sheet edits as a single undoable action
+     * @examplePrompt Run these operations together as one transaction
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.program.spreadsheet.transaction(
+     *   [
+     *     { method: "createSheet", args: { name: "Summary" } },
+     *     { method: "setValues", args: { sheetName: "Summary", values: [["A", 1]] } },
+     *   ],
+     *   "Build summary",
+     * )
+     * ```
+     */
+    abstract transaction(operations: PluginSpreadsheetTransactionOp[], label?: string): PluginApiReturn<PluginProgramSpreadsheetTransactionResult>;
+    /**
+     * Run an author-supplied script against a sandboxed workbook facade.
+     *
+     * The escape hatch for advanced automation the typed methods don't cover: the
+     * `script` runs against a restricted `workbook` object with browser/network
+     * globals blocked, and its return value is handed back as `result`. Prefer the
+     * typed methods where they exist. (Verb ruling: `run` executes a script.)
+     *
+     * @param script - Script source, run against the sandboxed `workbook` facade.
+     * @returns A {@linkcode PluginProgramSpreadsheetRunScriptResult} with the script's
+     *   `result`.
+     * @throws If the script uses a blocked browser/network API or throws at runtime.
+     *
+     * @examplePrompt Run this SpreadJS script against the workbook
+     * @examplePrompt Execute a custom script on the sheets
+     * @examplePrompt Run a script to tweak the workbook
+     *
+     * # Example
+     * ```ts
+     * const { result } = await snaptrude.program.spreadsheet.runScript(
+     *   "return workbook.getSheetCount();",
+     * )
+     * ```
+     */
+    abstract runScript(script: string): PluginApiReturn<PluginProgramSpreadsheetRunScriptResult>;
+    /**
+     * Read the recent audit log of program-spreadsheet operations.
+     *
+     * Returns the most recent operations performed through this API (method, sheet,
+     * status, summary, timestamp), newest first — useful for showing the user what
+     * a plugin changed. (Renamed from the host's `getRecentEntries` for §4 `get`
+     * compliance.)
+     *
+     * @param options - Optional `limit` on the entries returned (clamped 1–100,
+     *   default 20).
+     * @returns A {@linkcode PluginProgramSpreadsheetGetAuditLogResult} with the audit
+     *   `entries`, newest first.
+     *
+     * @examplePrompt Show the recent spreadsheet actions
+     * @examplePrompt What did the plugin change in the workbook?
+     * @examplePrompt Get the last 10 audit log entries
+     * @examplePrompt Read the program spreadsheet audit log
+     *
+     * # Example
+     * ```ts
+     * const { entries } = await snaptrude.program.spreadsheet.getAuditLog({ limit: 10 })
+     * ```
+     */
+    abstract getAuditLog(options?: {
+        limit?: number;
+    }): PluginApiReturn<PluginProgramSpreadsheetGetAuditLogResult>;
+    /**
+     * Ping the program-mode spreadsheet bridge to check it is reachable.
+     *
+     * A liveness probe: resolves with `{ pong: true }` when the program-mode
+     * workbook bridge is up. (Verb ruling: `ping` is a meta liveness verb.)
+     *
+     * @returns A {@linkcode PluginProgramSpreadsheetPingResult} — `{ pong: true }` when
+     *   the bridge is reachable.
+     *
+     * @examplePrompt Ping the spreadsheet bridge
+     * @examplePrompt Is the program spreadsheet available?
+     * @examplePrompt Check the spreadsheet connection is alive
+     *
+     * # Example
+     * ```ts
+     * const { pong } = await snaptrude.program.spreadsheet.ping()
+     * ```
+     */
+    abstract ping(): PluginApiReturn<PluginProgramSpreadsheetPingResult>;
+}
+/**
+ * Program-spreadsheet templates — capture a sheet's layout as a named, reusable
+ * template and re-apply it to another sheet.
+ *
+ * Accessed via `snaptrude.program.spreadsheet.templates`.
+ */
+export declare abstract class PluginProgramSpreadsheetTemplatesApi {
+    constructor();
+    /**
+     * Save a sheet's current layout as a named template.
+     *
+     * (Renamed from the host's `save` to `create` for §4 compliance.)
+     *
+     * @param name - Template name (re-saving the same name overwrites it).
+     * @param sheetName - The source sheet to capture.
+     * @param scope - Template scope: `"project"` (default) or `"global"`.
+     * @returns A {@linkcode PluginProgramSpreadsheetTemplatesCreateResult} with the new
+     *   template's `id`, `name`, `scope`, and source `sheetName`.
+     * @throws If the source sheet does not exist.
+     *
+     * @examplePrompt Save this sheet as a reusable template
+     * @examplePrompt Create a template from the Summary sheet
+     * @examplePrompt Save the current layout as a template called "Cover"
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.program.spreadsheet.templates.create("Cover", "Summary")
+     * ```
+     */
+    abstract create(name: string, sheetName: string, scope?: PluginSpreadsheetTemplateScope): PluginApiReturn<PluginProgramSpreadsheetTemplatesCreateResult>;
+    /**
+     * Apply a saved template to a target sheet (create-or-replace).
+     *
+     * @param name - The template to apply.
+     * @param targetSheetName - The sheet to create/replace from the template.
+     * @returns A {@linkcode PluginProgramSpreadsheetTemplatesApplyResult} echoing the
+     *   applied template and target sheet.
+     * @throws If the named template does not exist.
+     *
+     * @examplePrompt Apply the Cover template to a new sheet
+     * @examplePrompt Use my saved template on the Report sheet
+     * @examplePrompt Apply template "Cover" to sheet "Report"
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.program.spreadsheet.templates.apply("Cover", "Report")
+     * ```
+     */
+    abstract apply(name: string, targetSheetName: string): PluginApiReturn<PluginProgramSpreadsheetTemplatesApplyResult>;
+}
+/**
+ * Program-spreadsheet data bindings — bind a live program dataset to a sheet
+ * range so it can be refreshed on demand.
+ *
+ * A binding links a dataset (e.g. the takeoff) to a target sheet range; a refresh
+ * re-pulls the current data and rewrites the range. Accessed via
+ * `snaptrude.program.spreadsheet.bindings`.
+ */
+export declare abstract class PluginProgramSpreadsheetBindingsApi {
+    constructor();
+    /**
+     * Create a named binding from a dataset to a sheet range (and do an initial refresh).
+     *
+     * @param name - Binding name (re-using a name overwrites it).
+     * @param source - The dataset to bind (see
+     *   {@linkcode PluginSpreadsheetBindingSource}).
+     * @param target - The target sheet range (see
+     *   {@linkcode PluginSpreadsheetBindingTarget}).
+     * @param mode - How a refresh writes into the target (default `"replaceRange"`).
+     * @returns A {@linkcode PluginProgramSpreadsheetBindingsCreateResult} — the stored
+     *   binding plus the `refresh` result of the initial pull.
+     * @throws If the target sheet does not exist.
+     *
+     * @examplePrompt Bind the takeoff to the Data sheet
+     * @examplePrompt Create a live binding from the takeoff to A1 on Data
+     * @examplePrompt Link the takeoff dataset to a sheet range
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.program.spreadsheet.bindings.create(
+     *   "takeoff",
+     *   { dataset: "takeoff" },
+     *   { sheetName: "Data", startCell: "A1" },
+     * )
+     * ```
+     */
+    abstract create(name: string, source: PluginSpreadsheetBindingSource, target: PluginSpreadsheetBindingTarget, mode?: PluginSpreadsheetBindingMode): PluginApiReturn<PluginProgramSpreadsheetBindingsCreateResult>;
+    /**
+     * Refresh one binding (by name) or all bindings, re-pulling their source data.
+     *
+     * (Verb ruling: `refresh` re-pulls a binding's live source into its target
+     * range — distinct from {@linkcode PluginProgramSpreadsheetApi.recalculate},
+     * which recomputes formulas.)
+     *
+     * @param options - Optional binding `name`; omit it to refresh every binding.
+     * @returns A {@linkcode PluginProgramSpreadsheetBindingsRefreshResult} with a
+     *   `refreshed` entry per binding that was updated.
+     * @throws If a `name` is given but no binding with that name exists.
+     *
+     * @examplePrompt Refresh the takeoff binding
+     * @examplePrompt Re-pull all my data bindings
+     * @examplePrompt Refresh every binding on the sheets
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.program.spreadsheet.bindings.refresh({ name: "takeoff" })
+     * ```
+     */
+    abstract refresh(options?: {
+        name?: string;
+    }): PluginApiReturn<PluginProgramSpreadsheetBindingsRefreshResult>;
+    /**
+     * List all data bindings in the workbook.
+     *
+     * @returns A {@linkcode PluginProgramSpreadsheetBindingsListResult} with every
+     *   stored {@linkcode PluginSpreadsheetBinding}.
+     *
+     * @examplePrompt List the data bindings
+     * @examplePrompt What bindings are set up on the sheets?
+     * @examplePrompt Show all the live data bindings
+     *
+     * # Example
+     * ```ts
+     * const { bindings } = await snaptrude.program.spreadsheet.bindings.list()
+     * ```
+     */
+    abstract list(): PluginApiReturn<PluginProgramSpreadsheetBindingsListResult>;
+}
+/** A single spreadsheet cell value. */
+export declare const PluginSpreadsheetCell: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+export type PluginSpreadsheetCell = z.infer<typeof PluginSpreadsheetCell>;
+/** Horizontal alignment for a rendered column. */
+export declare const PluginSpreadsheetAlign: z.ZodEnum<{
+    center: "center";
+    left: "left";
+    right: "right";
+}>;
+export type PluginSpreadsheetAlign = z.infer<typeof PluginSpreadsheetAlign>;
+/**
+ * A column definition for {@linkcode PluginProgramSpreadsheetApi.render}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `key` | `string` | Key into each row object |
+ * | `header` | `string` | Column header text |
+ * | `width` | `number?` | Fixed column width in px; auto-fit when omitted |
+ * | `format` | `string?` | Number/date format string applied to the data cells |
+ * | `align` | `"left" \| "center" \| "right"?` | Cell alignment |
+ */
+export declare const PluginSpreadsheetColumn: z.ZodObject<{
+    key: z.ZodString;
+    header: z.ZodString;
+    width: z.ZodOptional<z.ZodNumber>;
+    format: z.ZodOptional<z.ZodString>;
+    align: z.ZodOptional<z.ZodEnum<{
+        center: "center";
+        left: "left";
+        right: "right";
+    }>>;
+}, z.core.$strip>;
+export type PluginSpreadsheetColumn = z.infer<typeof PluginSpreadsheetColumn>;
+/**
+ * A totals-row aggregation for {@linkcode PluginProgramSpreadsheetApi.render}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `column` | `string` | The {@linkcode PluginSpreadsheetColumn} `key` to aggregate |
+ * | `fn` | `"sum" \| "avg" \| "count" \| "min" \| "max"` | Aggregation function |
+ * | `label` | `string?` | Optional label printed in the first column of the totals row |
+ */
+export declare const PluginSpreadsheetTotal: z.ZodObject<{
+    column: z.ZodString;
+    fn: z.ZodEnum<{
+        min: "min";
+        max: "max";
+        count: "count";
+        sum: "sum";
+        avg: "avg";
+    }>;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginSpreadsheetTotal = z.infer<typeof PluginSpreadsheetTotal>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.render}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | Target sheet name |
+ * | `columns` | {@linkcode PluginSpreadsheetColumn}`[]` | Column definitions (at least one) |
+ * | `rows` | `Record<string, cell>[]` | Row objects keyed by column `key` |
+ * | `title` | `string?` | Optional title rendered above the header |
+ * | `startCell` | `string?` | Top-left anchor in A1 notation (default `"A1"`) |
+ * | `whenExists` | `"replace" \| "error"?` | Behaviour if the sheet exists (default `"replace"`) |
+ * | `asTable` | `boolean?` | Wrap the block in a table (default `true`) |
+ * | `freezeHeader` | `boolean?` | Freeze rows above the data (default `true`) |
+ * | `totals` | {@linkcode PluginSpreadsheetTotal}`[]?` | Optional totals row |
+ */
+export declare const PluginProgramSpreadsheetRenderArgs: z.ZodObject<{
+    sheetName: z.ZodString;
+    columns: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        header: z.ZodString;
+        width: z.ZodOptional<z.ZodNumber>;
+        format: z.ZodOptional<z.ZodString>;
+        align: z.ZodOptional<z.ZodEnum<{
+            center: "center";
+            left: "left";
+            right: "right";
+        }>>;
+    }, z.core.$strip>>;
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    title: z.ZodOptional<z.ZodString>;
+    startCell: z.ZodOptional<z.ZodString>;
+    whenExists: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        replace: "replace";
+    }>>;
+    asTable: z.ZodOptional<z.ZodBoolean>;
+    freezeHeader: z.ZodOptional<z.ZodBoolean>;
+    totals: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        column: z.ZodString;
+        fn: z.ZodEnum<{
+            min: "min";
+            max: "max";
+            count: "count";
+            sum: "sum";
+            avg: "avg";
+        }>;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetRenderArgs = z.infer<typeof PluginProgramSpreadsheetRenderArgs>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.render}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | The sheet that was written |
+ * | `range` | `string` | A1 range covering the full written block (title + header + data + totals) |
+ * | `headerRange` | `string` | A1 range of the header row alone |
+ * | `rowCount` | `number` | Number of data rows written (excludes title/header/totals) |
+ * | `colCount` | `number` | Number of columns written |
+ * | `tableName` | `string \| null` | The created table's name, or `null` when not wrapped as a table |
+ * | `replaced` | `boolean` | Whether an existing sheet was replaced |
+ */
+export declare const PluginProgramSpreadsheetRenderResult: z.ZodObject<{
+    sheetName: z.ZodString;
+    range: z.ZodString;
+    headerRange: z.ZodString;
+    rowCount: z.ZodNumber;
+    colCount: z.ZodNumber;
+    tableName: z.ZodNullable<z.ZodString>;
+    replaced: z.ZodBoolean;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetRenderResult = z.infer<typeof PluginProgramSpreadsheetRenderResult>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.renderTakeoff} and
+ * {@linkcode PluginProgramSpreadsheetApi.renderProgram} — the dataset render
+ * methods. There is **no data argument**: the host pulls and projects the
+ * takeoff/program dataset itself. All fields are optional. (Both methods share
+ * this args type, as `import.image`/`import.pdf` share their args.)
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string?` | Target sheet name (a default is used when omitted) |
+ * | `title` | `string?` | Optional title rendered above the table |
+ * | `filter` | `string?` | Optional dataset-filter expression to narrow the rows |
+ */
+export declare const PluginProgramSpreadsheetRenderDatasetArgs: z.ZodObject<{
+    sheetName: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    filter: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetRenderDatasetArgs = z.infer<typeof PluginProgramSpreadsheetRenderDatasetArgs>;
+/** The workbook export file format. */
+export declare const PluginSpreadsheetExportFormat: z.ZodEnum<{
+    pdf: "pdf";
+    xlsx: "xlsx";
+    csv: "csv";
+}>;
+export type PluginSpreadsheetExportFormat = z.infer<typeof PluginSpreadsheetExportFormat>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.export}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `format` | `"xlsx" \| "pdf" \| "csv"` | The file format to export the workbook to |
+ * | `fileName` | `string?` | Desired file name (without extension); a default is used when omitted |
+ */
+export declare const PluginProgramSpreadsheetExportArgs: z.ZodObject<{
+    format: z.ZodEnum<{
+        pdf: "pdf";
+        xlsx: "xlsx";
+        csv: "csv";
+    }>;
+    fileName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetExportArgs = z.infer<typeof PluginProgramSpreadsheetExportArgs>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.export} — the exported workbook file.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `format` | `"xlsx" \| "pdf" \| "csv"` | The format the file was exported in |
+ * | `fileName` | `string` | The file name (with extension) |
+ * | `mimeType` | `string` | The file's MIME type |
+ * | `dataBase64` | `string` | The file's bytes, base64-encoded |
+ */
+export declare const PluginProgramSpreadsheetExportResult: z.ZodObject<{
+    format: z.ZodEnum<{
+        pdf: "pdf";
+        xlsx: "xlsx";
+        csv: "csv";
+    }>;
+    fileName: z.ZodString;
+    mimeType: z.ZodString;
+    dataBase64: z.ZodString;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetExportResult = z.infer<typeof PluginProgramSpreadsheetExportResult>;
+/**
+ * Metadata for one sheet in {@linkcode PluginProgramSpreadsheetListSheetsResult}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Sheet name |
+ * | `index` | `number` | Zero-based sheet index |
+ * | `visible` | `boolean` | Whether the sheet is visible |
+ * | `rowCount` | `number` | Total rows in the sheet |
+ * | `colCount` | `number` | Total columns in the sheet |
+ */
+export declare const PluginSpreadsheetSheetInfo: z.ZodObject<{
+    name: z.ZodString;
+    index: z.ZodNumber;
+    visible: z.ZodBoolean;
+    rowCount: z.ZodNumber;
+    colCount: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginSpreadsheetSheetInfo = z.infer<typeof PluginSpreadsheetSheetInfo>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.listSheets}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheets` | {@linkcode PluginSpreadsheetSheetInfo}`[]` | All sheets in the workbook |
+ * | `activeSheet` | `string \| null` | The active sheet name, or `null` |
+ */
+export declare const PluginProgramSpreadsheetListSheetsResult: z.ZodObject<{
+    sheets: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        index: z.ZodNumber;
+        visible: z.ZodBoolean;
+        rowCount: z.ZodNumber;
+        colCount: z.ZodNumber;
+    }, z.core.$strip>>;
+    activeSheet: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetListSheetsResult = z.infer<typeof PluginProgramSpreadsheetListSheetsResult>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.getSheetData}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | Sheet to read |
+ * | `range` | `string?` | A1 range; defaults to the sheet's used range |
+ * | `header` | `boolean?` | When `true`, also return records keyed by the first (header) row |
+ */
+export declare const PluginProgramSpreadsheetGetSheetDataArgs: z.ZodObject<{
+    sheetName: z.ZodString;
+    range: z.ZodOptional<z.ZodString>;
+    header: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetGetSheetDataArgs = z.infer<typeof PluginProgramSpreadsheetGetSheetDataArgs>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.getSheetData}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | The sheet that was read |
+ * | `range` | `string` | A1 range that was read |
+ * | `values` | `cell[][]` | Row-major matrix of cell values |
+ * | `records` | `Record<string, cell>[]?` | Present only when `header` was `true`: rows keyed by header |
+ */
+export declare const PluginProgramSpreadsheetGetSheetDataResult: z.ZodObject<{
+    sheetName: z.ZodString;
+    range: z.ZodString;
+    values: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    records: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetGetSheetDataResult = z.infer<typeof PluginProgramSpreadsheetGetSheetDataResult>;
+/** Chart type for {@linkcode PluginProgramSpreadsheetApi.addChart}. */
+export declare const PluginSpreadsheetChartType: z.ZodEnum<{
+    line: "line";
+    area: "area";
+    column: "column";
+    bar: "bar";
+    pie: "pie";
+    scatter: "scatter";
+}>;
+export type PluginSpreadsheetChartType = z.infer<typeof PluginSpreadsheetChartType>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.addChart}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | Sheet to add the chart to |
+ * | `chartType` | `"column" \| "bar" \| "line" \| "pie" \| "area" \| "scatter"` | Chart type |
+ * | `dataRange` | `string` | A1 range driving the chart |
+ * | `title` | `string?` | Optional chart title |
+ * | `position` | `{ x; y }?` | Top-left position (sheet coords) |
+ * | `size` | `{ width; height }?` | Chart size in px |
+ */
+export declare const PluginProgramSpreadsheetAddChartArgs: z.ZodObject<{
+    sheetName: z.ZodString;
+    chartType: z.ZodEnum<{
+        line: "line";
+        area: "area";
+        column: "column";
+        bar: "bar";
+        pie: "pie";
+        scatter: "scatter";
+    }>;
+    dataRange: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    position: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>>;
+    size: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetAddChartArgs = z.infer<typeof PluginProgramSpreadsheetAddChartArgs>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.addChart}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `chartId` | `string` | Id of the created chart |
+ */
+export declare const PluginProgramSpreadsheetAddChartResult: z.ZodObject<{
+    chartId: z.ZodString;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetAddChartResult = z.infer<typeof PluginProgramSpreadsheetAddChartResult>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.highlightCells}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | Sheet containing the range |
+ * | `range` | `string` | A1 range to highlight |
+ * | `color` | `string?` | CSS hex background color (a default emphasis is used when omitted) |
+ * | `bold` | `boolean?` | Also bold the text |
+ */
+export declare const PluginProgramSpreadsheetHighlightCellsArgs: z.ZodObject<{
+    sheetName: z.ZodString;
+    range: z.ZodString;
+    color: z.ZodOptional<z.ZodString>;
+    bold: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetHighlightCellsArgs = z.infer<typeof PluginProgramSpreadsheetHighlightCellsArgs>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.highlightCells}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | The sheet that was highlighted |
+ * | `range` | `string` | The range that was highlighted |
+ */
+export declare const PluginProgramSpreadsheetHighlightCellsResult: z.ZodObject<{
+    sheetName: z.ZodString;
+    range: z.ZodString;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetHighlightCellsResult = z.infer<typeof PluginProgramSpreadsheetHighlightCellsResult>;
+/**
+ * One department row in the area-program dataset. Areas are in the enclosing
+ * {@linkcode PluginProgramSpreadsheetGetProgramResult}'s `units`. This mirrors
+ * {@linkcode PluginProgramDepartmentMetric}, plus a derived `variance`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `departmentId` | `string` | Department id |
+ * | `name` | `string` | Department name |
+ * | `targetArea` | `number \| null` | Target area, or `null` if no target is set |
+ * | `allocatedArea` | `number` | Area currently allocated to this department |
+ * | `variance` | `number \| null` | `allocatedArea − targetArea`, or `null` when no target |
+ */
+export declare const PluginSpreadsheetProgramRow: z.ZodObject<{
+    departmentId: z.ZodString;
+    name: z.ZodString;
+    targetArea: z.ZodNullable<z.ZodNumber>;
+    allocatedArea: z.ZodNumber;
+    variance: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type PluginSpreadsheetProgramRow = z.infer<typeof PluginSpreadsheetProgramRow>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.getProgram} — the area-program
+ * dataset {@linkcode PluginProgramSpreadsheetApi.renderProgram} draws. For the
+ * canonical summary read, see {@linkcode PluginProgramMetricsApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `units` | `"ft2" \| "m2"` | The unit every area in this dataset is reported in |
+ * | `rows` | {@linkcode PluginSpreadsheetProgramRow}`[]` | Per-department program rows |
+ * | `totalTargetArea` | `number` | Sum of all department target areas |
+ * | `totalAllocatedArea` | `number` | Total allocated area |
+ * | `generatedAt` | `string` | ISO timestamp of when the dataset was projected |
+ */
+export declare const PluginProgramSpreadsheetGetProgramResult: z.ZodObject<{
+    units: z.ZodEnum<{
+        ft2: "ft2";
+        m2: "m2";
+    }>;
+    rows: z.ZodArray<z.ZodObject<{
+        departmentId: z.ZodString;
+        name: z.ZodString;
+        targetArea: z.ZodNullable<z.ZodNumber>;
+        allocatedArea: z.ZodNumber;
+        variance: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+    totalTargetArea: z.ZodNumber;
+    totalAllocatedArea: z.ZodNumber;
+    generatedAt: z.ZodString;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetGetProgramResult = z.infer<typeof PluginProgramSpreadsheetGetProgramResult>;
+/**
+ * One family-aggregated row in the quantity/material takeoff dataset. The takeoff
+ * is grouped by object type + category + family (not per element), so each row is
+ * a rolled-up quantity for that family.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `objectType` | `string` | Element object type (e.g. `"Wall"`, `"Door"`, `"Window"`) |
+ * | `category` | `string` | Element category |
+ * | `family` | `string` | Element family the quantity is aggregated over |
+ * | `quantity` | `number` | Aggregated quantity in `unit` |
+ * | `unit` | `string` | Quantity unit (e.g. `"m"` for length, `"m2"` for area) |
+ */
+export declare const PluginSpreadsheetTakeoffRow: z.ZodObject<{
+    objectType: z.ZodString;
+    category: z.ZodString;
+    family: z.ZodString;
+    quantity: z.ZodNumber;
+    unit: z.ZodString;
+}, z.core.$strip>;
+export type PluginSpreadsheetTakeoffRow = z.infer<typeof PluginSpreadsheetTakeoffRow>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.getTakeoff} — the takeoff dataset
+ * {@linkcode PluginProgramSpreadsheetApi.renderTakeoff} draws.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `rows` | {@linkcode PluginSpreadsheetTakeoffRow}`[]` | One row per aggregated object-type/category/family group |
+ * | `rowCount` | `number` | Number of rows |
+ * | `generatedAt` | `string` | ISO timestamp of when the dataset was read |
+ */
+export declare const PluginProgramSpreadsheetGetTakeoffResult: z.ZodObject<{
+    rows: z.ZodArray<z.ZodObject<{
+        objectType: z.ZodString;
+        category: z.ZodString;
+        family: z.ZodString;
+        quantity: z.ZodNumber;
+        unit: z.ZodString;
+    }, z.core.$strip>>;
+    rowCount: z.ZodNumber;
+    generatedAt: z.ZodString;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetGetTakeoffResult = z.infer<typeof PluginProgramSpreadsheetGetTakeoffResult>;
+/** Behaviour when {@linkcode PluginProgramSpreadsheetApi.createSheet} targets an existing sheet name. */
+export declare const PluginSpreadsheetWhenExists: z.ZodEnum<{
+    error: "error";
+    replace: "replace";
+    reuse: "reuse";
+}>;
+export type PluginSpreadsheetWhenExists = z.infer<typeof PluginSpreadsheetWhenExists>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.createSheet}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | The sheet name to create |
+ * | `whenExists` | `"reuse" \| "replace" \| "error"?` | Behaviour if the name exists (default `"reuse"`) |
+ */
+export declare const PluginProgramSpreadsheetCreateSheetArgs: z.ZodObject<{
+    name: z.ZodString;
+    whenExists: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        replace: "replace";
+        reuse: "reuse";
+    }>>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetCreateSheetArgs = z.infer<typeof PluginProgramSpreadsheetCreateSheetArgs>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.createSheet}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | The resolved sheet name |
+ * | `replaced` | `boolean` | Whether an existing sheet was replaced/cleared |
+ * | `sheetIndex` | `number \| null` | Zero-based index of the sheet, or `null` if unknown |
+ */
+export declare const PluginProgramSpreadsheetCreateSheetResult: z.ZodObject<{
+    sheetName: z.ZodString;
+    replaced: z.ZodBoolean;
+    sheetIndex: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetCreateSheetResult = z.infer<typeof PluginProgramSpreadsheetCreateSheetResult>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.setValues}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | Sheet to write into |
+ * | `values` | `cell[][]` | Row-major matrix of values to write |
+ * | `startCell` | `string?` | Top-left anchor in A1 notation (default `"A1"`) |
+ */
+export declare const PluginProgramSpreadsheetSetValuesArgs: z.ZodObject<{
+    sheetName: z.ZodString;
+    values: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    startCell: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetSetValuesArgs = z.infer<typeof PluginProgramSpreadsheetSetValuesArgs>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.setValues}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | The sheet that was written |
+ * | `startCell` | `string` | The anchor cell values were written from |
+ * | `rowCount` | `number` | Number of rows written |
+ * | `colCount` | `number` | Widest row's column count |
+ */
+export declare const PluginProgramSpreadsheetSetValuesResult: z.ZodObject<{
+    sheetName: z.ZodString;
+    startCell: z.ZodString;
+    rowCount: z.ZodNumber;
+    colCount: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetSetValuesResult = z.infer<typeof PluginProgramSpreadsheetSetValuesResult>;
+/**
+ * A single cell formula for {@linkcode PluginProgramSpreadsheetApi.setFormulas}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `cell` | `string` | Target cell in A1 notation |
+ * | `formula` | `string` | Formula expression (a leading `=` is optional) |
+ */
+export declare const PluginSpreadsheetFormula: z.ZodObject<{
+    cell: z.ZodString;
+    formula: z.ZodString;
+}, z.core.$strip>;
+export type PluginSpreadsheetFormula = z.infer<typeof PluginSpreadsheetFormula>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.setFormulas}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | Sheet to set formulas on |
+ * | `formulas` | {@linkcode PluginSpreadsheetFormula}`[]` | The cell → formula assignments |
+ */
+export declare const PluginProgramSpreadsheetSetFormulasArgs: z.ZodObject<{
+    sheetName: z.ZodString;
+    formulas: z.ZodArray<z.ZodObject<{
+        cell: z.ZodString;
+        formula: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetSetFormulasArgs = z.infer<typeof PluginProgramSpreadsheetSetFormulasArgs>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.setFormulas}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | The sheet that was written |
+ * | `count` | `number` | Number of formulas set |
+ */
+export declare const PluginProgramSpreadsheetSetFormulasResult: z.ZodObject<{
+    sheetName: z.ZodString;
+    count: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetSetFormulasResult = z.infer<typeof PluginProgramSpreadsheetSetFormulasResult>;
+/** Font weight for a {@linkcode PluginSpreadsheetCellStyle}. */
+export declare const PluginSpreadsheetFontWeight: z.ZodEnum<{
+    normal: "normal";
+    bold: "bold";
+}>;
+export type PluginSpreadsheetFontWeight = z.infer<typeof PluginSpreadsheetFontWeight>;
+/** Font style for a {@linkcode PluginSpreadsheetCellStyle}. */
+export declare const PluginSpreadsheetFontStyle: z.ZodEnum<{
+    normal: "normal";
+    italic: "italic";
+}>;
+export type PluginSpreadsheetFontStyle = z.infer<typeof PluginSpreadsheetFontStyle>;
+/** Horizontal cell alignment for a {@linkcode PluginSpreadsheetCellStyle}. */
+export declare const PluginSpreadsheetHorizontalAlign: z.ZodEnum<{
+    center: "center";
+    left: "left";
+    right: "right";
+    general: "general";
+}>;
+export type PluginSpreadsheetHorizontalAlign = z.infer<typeof PluginSpreadsheetHorizontalAlign>;
+/** Vertical cell alignment for a {@linkcode PluginSpreadsheetCellStyle}. */
+export declare const PluginSpreadsheetVerticalAlign: z.ZodEnum<{
+    center: "center";
+    top: "top";
+    bottom: "bottom";
+}>;
+export type PluginSpreadsheetVerticalAlign = z.infer<typeof PluginSpreadsheetVerticalAlign>;
+/**
+ * A cell style for {@linkcode PluginProgramSpreadsheetApi.setStyles}. All fields
+ * are optional; only the ones provided are applied.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `backColor` | `string?` | Background (fill) color, CSS hex |
+ * | `foreColor` | `string?` | Text color, CSS hex |
+ * | `font` | `string?` | Full CSS font shorthand (overrides the parts below) |
+ * | `fontFamily` | `string?` | Font family |
+ * | `fontSize` | `number?` | Font size in px |
+ * | `fontWeight` | `"normal" \| "bold"?` | Font weight |
+ * | `fontStyle` | `"normal" \| "italic"?` | Font style |
+ * | `formatter` | `string?` | Number/date format string |
+ * | `horizontalAlign` | `"left" \| "center" \| "right" \| "general"?` | Horizontal alignment |
+ * | `verticalAlign` | `"top" \| "center" \| "bottom"?` | Vertical alignment |
+ */
+export declare const PluginSpreadsheetCellStyle: z.ZodObject<{
+    backColor: z.ZodOptional<z.ZodString>;
+    foreColor: z.ZodOptional<z.ZodString>;
+    font: z.ZodOptional<z.ZodString>;
+    fontFamily: z.ZodOptional<z.ZodString>;
+    fontSize: z.ZodOptional<z.ZodNumber>;
+    fontWeight: z.ZodOptional<z.ZodEnum<{
+        normal: "normal";
+        bold: "bold";
+    }>>;
+    fontStyle: z.ZodOptional<z.ZodEnum<{
+        normal: "normal";
+        italic: "italic";
+    }>>;
+    formatter: z.ZodOptional<z.ZodString>;
+    horizontalAlign: z.ZodOptional<z.ZodEnum<{
+        center: "center";
+        left: "left";
+        right: "right";
+        general: "general";
+    }>>;
+    verticalAlign: z.ZodOptional<z.ZodEnum<{
+        center: "center";
+        top: "top";
+        bottom: "bottom";
+    }>>;
+}, z.core.$strip>;
+export type PluginSpreadsheetCellStyle = z.infer<typeof PluginSpreadsheetCellStyle>;
+/**
+ * A range + the style to apply to it, for {@linkcode PluginProgramSpreadsheetApi.setStyles}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `range` | `string` | A1 range to style |
+ * | `style` | {@linkcode PluginSpreadsheetCellStyle} | The style to apply |
+ */
+export declare const PluginSpreadsheetRangeStyle: z.ZodObject<{
+    range: z.ZodString;
+    style: z.ZodObject<{
+        backColor: z.ZodOptional<z.ZodString>;
+        foreColor: z.ZodOptional<z.ZodString>;
+        font: z.ZodOptional<z.ZodString>;
+        fontFamily: z.ZodOptional<z.ZodString>;
+        fontSize: z.ZodOptional<z.ZodNumber>;
+        fontWeight: z.ZodOptional<z.ZodEnum<{
+            normal: "normal";
+            bold: "bold";
+        }>>;
+        fontStyle: z.ZodOptional<z.ZodEnum<{
+            normal: "normal";
+            italic: "italic";
+        }>>;
+        formatter: z.ZodOptional<z.ZodString>;
+        horizontalAlign: z.ZodOptional<z.ZodEnum<{
+            center: "center";
+            left: "left";
+            right: "right";
+            general: "general";
+        }>>;
+        verticalAlign: z.ZodOptional<z.ZodEnum<{
+            center: "center";
+            top: "top";
+            bottom: "bottom";
+        }>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type PluginSpreadsheetRangeStyle = z.infer<typeof PluginSpreadsheetRangeStyle>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.setStyles}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | Sheet containing the ranges |
+ * | `ranges` | {@linkcode PluginSpreadsheetRangeStyle}`[]` | Range → style assignments |
+ */
+export declare const PluginProgramSpreadsheetSetStylesArgs: z.ZodObject<{
+    sheetName: z.ZodString;
+    ranges: z.ZodArray<z.ZodObject<{
+        range: z.ZodString;
+        style: z.ZodObject<{
+            backColor: z.ZodOptional<z.ZodString>;
+            foreColor: z.ZodOptional<z.ZodString>;
+            font: z.ZodOptional<z.ZodString>;
+            fontFamily: z.ZodOptional<z.ZodString>;
+            fontSize: z.ZodOptional<z.ZodNumber>;
+            fontWeight: z.ZodOptional<z.ZodEnum<{
+                normal: "normal";
+                bold: "bold";
+            }>>;
+            fontStyle: z.ZodOptional<z.ZodEnum<{
+                normal: "normal";
+                italic: "italic";
+            }>>;
+            formatter: z.ZodOptional<z.ZodString>;
+            horizontalAlign: z.ZodOptional<z.ZodEnum<{
+                center: "center";
+                left: "left";
+                right: "right";
+                general: "general";
+            }>>;
+            verticalAlign: z.ZodOptional<z.ZodEnum<{
+                center: "center";
+                top: "top";
+                bottom: "bottom";
+            }>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetSetStylesArgs = z.infer<typeof PluginProgramSpreadsheetSetStylesArgs>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.setStyles}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | The sheet that was styled |
+ * | `count` | `number` | Number of ranges styled |
+ */
+export declare const PluginProgramSpreadsheetSetStylesResult: z.ZodObject<{
+    sheetName: z.ZodString;
+    count: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetSetStylesResult = z.infer<typeof PluginProgramSpreadsheetSetStylesResult>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.mergeCells}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | Sheet containing the range |
+ * | `range` | `string` | A1 range to merge into one spanned cell |
+ * | `value` | `cell?` | Optional value to set in the merged (top-left) cell |
+ */
+export declare const PluginProgramSpreadsheetMergeCellsArgs: z.ZodObject<{
+    sheetName: z.ZodString;
+    range: z.ZodString;
+    value: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetMergeCellsArgs = z.infer<typeof PluginProgramSpreadsheetMergeCellsArgs>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.mergeCells}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | The sheet that was merged |
+ * | `range` | `string` | The range that was merged |
+ */
+export declare const PluginProgramSpreadsheetMergeCellsResult: z.ZodObject<{
+    sheetName: z.ZodString;
+    range: z.ZodString;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetMergeCellsResult = z.infer<typeof PluginProgramSpreadsheetMergeCellsResult>;
+/** Conditional-formatting rule type. Currently only `dataBar`; more are reserved. */
+export declare const PluginSpreadsheetConditionalRuleType: z.ZodEnum<{
+    dataBar: "dataBar";
+}>;
+export type PluginSpreadsheetConditionalRuleType = z.infer<typeof PluginSpreadsheetConditionalRuleType>;
+/**
+ * A conditional-formatting rule for {@linkcode PluginProgramSpreadsheetApi.addConditionalFormatting}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `type` | `"dataBar"` | The rule kind (a proportional in-cell bar) |
+ * | `color` | `string?` | Bar color, CSS hex (a default is used when omitted) |
+ */
+export declare const PluginSpreadsheetConditionalRule: z.ZodObject<{
+    type: z.ZodEnum<{
+        dataBar: "dataBar";
+    }>;
+    color: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginSpreadsheetConditionalRule = z.infer<typeof PluginSpreadsheetConditionalRule>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.addConditionalFormatting}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | Sheet containing the range |
+ * | `range` | `string` | A1 range to format |
+ * | `rule` | {@linkcode PluginSpreadsheetConditionalRule} | The conditional-format rule |
+ */
+export declare const PluginProgramSpreadsheetAddConditionalFormattingArgs: z.ZodObject<{
+    sheetName: z.ZodString;
+    range: z.ZodString;
+    rule: z.ZodObject<{
+        type: z.ZodEnum<{
+            dataBar: "dataBar";
+        }>;
+        color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetAddConditionalFormattingArgs = z.infer<typeof PluginProgramSpreadsheetAddConditionalFormattingArgs>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.addConditionalFormatting}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | The sheet that was formatted |
+ * | `range` | `string` | The range the rule was applied to |
+ * | `created` | `boolean` | Whether a data-bar rule was created (vs a fallback fill) |
+ */
+export declare const PluginProgramSpreadsheetAddConditionalFormattingResult: z.ZodObject<{
+    sheetName: z.ZodString;
+    range: z.ZodString;
+    created: z.ZodBoolean;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetAddConditionalFormattingResult = z.infer<typeof PluginProgramSpreadsheetAddConditionalFormattingResult>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.recalculate}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string?` | A sheet to focus before recalculating; omit for the whole workbook |
+ */
+export declare const PluginProgramSpreadsheetRecalculateArgs: z.ZodObject<{
+    sheetName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetRecalculateArgs = z.infer<typeof PluginProgramSpreadsheetRecalculateArgs>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.recalculate}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `scope` | `"sheet" \| "workbook"` | Whether a single sheet was focused or the whole workbook |
+ * | `sheetName` | `string \| null` | The focused sheet, or `null` for a workbook-wide recompute |
+ */
+export declare const PluginProgramSpreadsheetRecalculateResult: z.ZodObject<{
+    scope: z.ZodEnum<{
+        sheet: "sheet";
+        workbook: "workbook";
+    }>;
+    sheetName: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetRecalculateResult = z.infer<typeof PluginProgramSpreadsheetRecalculateResult>;
+/** A batchable operation name for {@linkcode PluginProgramSpreadsheetApi.transaction}. */
+export declare const PluginSpreadsheetTransactionMethod: z.ZodEnum<{
+    createSheet: "createSheet";
+    setValues: "setValues";
+    setFormulas: "setFormulas";
+    setStyles: "setStyles";
+    mergeCells: "mergeCells";
+}>;
+export type PluginSpreadsheetTransactionMethod = z.infer<typeof PluginSpreadsheetTransactionMethod>;
+/**
+ * One operation within a {@linkcode PluginProgramSpreadsheetApi.transaction}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `method` | {@linkcode PluginSpreadsheetTransactionMethod} | The batchable method to run |
+ * | `args` | `unknown` | The `method`'s own arguments object |
+ */
+export declare const PluginSpreadsheetTransactionOp: z.ZodObject<{
+    method: z.ZodEnum<{
+        createSheet: "createSheet";
+        setValues: "setValues";
+        setFormulas: "setFormulas";
+        setStyles: "setStyles";
+        mergeCells: "mergeCells";
+    }>;
+    args: z.ZodUnknown;
+}, z.core.$strip>;
+export type PluginSpreadsheetTransactionOp = z.infer<typeof PluginSpreadsheetTransactionOp>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.transaction}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `operations` | {@linkcode PluginSpreadsheetTransactionOp}`[]` | The operations to run in order |
+ * | `label` | `string?` | Undo-history label for the batch |
+ */
+export declare const PluginProgramSpreadsheetTransactionArgs: z.ZodObject<{
+    operations: z.ZodArray<z.ZodObject<{
+        method: z.ZodEnum<{
+            createSheet: "createSheet";
+            setValues: "setValues";
+            setFormulas: "setFormulas";
+            setStyles: "setStyles";
+            mergeCells: "mergeCells";
+        }>;
+        args: z.ZodUnknown;
+    }, z.core.$strip>>;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetTransactionArgs = z.infer<typeof PluginProgramSpreadsheetTransactionArgs>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.transaction}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `label` | `string` | The undo-history label used |
+ * | `operationCount` | `number` | Number of operations run |
+ * | `results` | `unknown[]` | Each operation's result, in order |
+ */
+export declare const PluginProgramSpreadsheetTransactionResult: z.ZodObject<{
+    label: z.ZodString;
+    operationCount: z.ZodNumber;
+    results: z.ZodArray<z.ZodUnknown>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetTransactionResult = z.infer<typeof PluginProgramSpreadsheetTransactionResult>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.runScript}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `script` | `string` | Script source, run against a sandboxed `workbook` facade |
+ */
+export declare const PluginProgramSpreadsheetRunScriptArgs: z.ZodObject<{
+    script: z.ZodString;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetRunScriptArgs = z.infer<typeof PluginProgramSpreadsheetRunScriptArgs>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.runScript}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `result` | `unknown` | The script's return value (`null` when it returns nothing) |
+ */
+export declare const PluginProgramSpreadsheetRunScriptResult: z.ZodObject<{
+    result: z.ZodUnknown;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetRunScriptResult = z.infer<typeof PluginProgramSpreadsheetRunScriptResult>;
+/** Status of an audit-log entry. */
+export declare const PluginSpreadsheetAuditStatus: z.ZodEnum<{
+    error: "error";
+    success: "success";
+}>;
+export type PluginSpreadsheetAuditStatus = z.infer<typeof PluginSpreadsheetAuditStatus>;
+/**
+ * One entry in the program-spreadsheet audit log.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Entry id |
+ * | `pluginId` | `string` | Id of the plugin that performed the operation |
+ * | `method` | `string` | The API method invoked |
+ * | `label` | `string?` | Optional operation label |
+ * | `sheetName` | `string?` | The sheet the operation targeted, if any |
+ * | `timestamp` | `string` | ISO timestamp |
+ * | `status` | `"success" \| "error"` | Whether the operation succeeded |
+ * | `summary` | `string?` | Short human-readable summary |
+ */
+export declare const PluginSpreadsheetAuditEntry: z.ZodObject<{
+    id: z.ZodString;
+    pluginId: z.ZodString;
+    method: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    sheetName: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodString;
+    status: z.ZodEnum<{
+        error: "error";
+        success: "success";
+    }>;
+    summary: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginSpreadsheetAuditEntry = z.infer<typeof PluginSpreadsheetAuditEntry>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.getAuditLog}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `limit` | `number?` | Max entries to return (clamped 1–100, default 20) |
+ */
+export declare const PluginProgramSpreadsheetGetAuditLogArgs: z.ZodObject<{
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetGetAuditLogArgs = z.infer<typeof PluginProgramSpreadsheetGetAuditLogArgs>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.getAuditLog}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `entries` | {@linkcode PluginSpreadsheetAuditEntry}`[]` | Recent audit entries, newest first |
+ */
+export declare const PluginProgramSpreadsheetGetAuditLogResult: z.ZodObject<{
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        pluginId: z.ZodString;
+        method: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        sheetName: z.ZodOptional<z.ZodString>;
+        timestamp: z.ZodString;
+        status: z.ZodEnum<{
+            error: "error";
+            success: "success";
+        }>;
+        summary: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetGetAuditLogResult = z.infer<typeof PluginProgramSpreadsheetGetAuditLogResult>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.ping}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `pong` | `boolean` | `true` when the program-mode spreadsheet bridge is reachable |
+ */
+export declare const PluginProgramSpreadsheetPingResult: z.ZodObject<{
+    pong: z.ZodBoolean;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetPingResult = z.infer<typeof PluginProgramSpreadsheetPingResult>;
+/** The visibility scope of a saved template. */
+export declare const PluginSpreadsheetTemplateScope: z.ZodEnum<{
+    project: "project";
+    global: "global";
+}>;
+export type PluginSpreadsheetTemplateScope = z.infer<typeof PluginSpreadsheetTemplateScope>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetTemplatesApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Template name (re-saving the same name overwrites it) |
+ * | `sheetName` | `string` | The source sheet to capture |
+ * | `scope` | `"project" \| "global"?` | Template scope (default `"project"`) |
+ */
+export declare const PluginProgramSpreadsheetTemplatesCreateArgs: z.ZodObject<{
+    name: z.ZodString;
+    sheetName: z.ZodString;
+    scope: z.ZodOptional<z.ZodEnum<{
+        project: "project";
+        global: "global";
+    }>>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetTemplatesCreateArgs = z.infer<typeof PluginProgramSpreadsheetTemplatesCreateArgs>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetTemplatesApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The new template's id |
+ * | `name` | `string` | The template name |
+ * | `scope` | `"project" \| "global"` | The template scope |
+ * | `sheetName` | `string` | The source sheet captured |
+ */
+export declare const PluginProgramSpreadsheetTemplatesCreateResult: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    scope: z.ZodEnum<{
+        project: "project";
+        global: "global";
+    }>;
+    sheetName: z.ZodString;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetTemplatesCreateResult = z.infer<typeof PluginProgramSpreadsheetTemplatesCreateResult>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetTemplatesApi.apply}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | The template to apply |
+ * | `targetSheetName` | `string` | The sheet to create/replace from the template |
+ */
+export declare const PluginProgramSpreadsheetTemplatesApplyArgs: z.ZodObject<{
+    name: z.ZodString;
+    targetSheetName: z.ZodString;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetTemplatesApplyArgs = z.infer<typeof PluginProgramSpreadsheetTemplatesApplyArgs>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetTemplatesApi.apply}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | The template that was applied |
+ * | `targetSheetName` | `string` | The sheet it was applied to |
+ */
+export declare const PluginProgramSpreadsheetTemplatesApplyResult: z.ZodObject<{
+    name: z.ZodString;
+    targetSheetName: z.ZodString;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetTemplatesApplyResult = z.infer<typeof PluginProgramSpreadsheetTemplatesApplyResult>;
+/**
+ * A binding's data source. Currently only the takeoff dataset; `program` is
+ * reserved for a future source.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `dataset` | `"takeoff"` | The dataset the binding pulls from |
+ */
+export declare const PluginSpreadsheetBindingSource: z.ZodObject<{
+    dataset: z.ZodEnum<{
+        takeoff: "takeoff";
+    }>;
+}, z.core.$strip>;
+export type PluginSpreadsheetBindingSource = z.infer<typeof PluginSpreadsheetBindingSource>;
+/** How a binding refresh writes into its target range. Currently only `replaceRange`. */
+export declare const PluginSpreadsheetBindingMode: z.ZodEnum<{
+    replaceRange: "replaceRange";
+}>;
+export type PluginSpreadsheetBindingMode = z.infer<typeof PluginSpreadsheetBindingMode>;
+/**
+ * A binding's target range, for {@linkcode PluginProgramSpreadsheetBindingsApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | The sheet to write into |
+ * | `startCell` | `string?` | Top-left anchor in A1 notation (default `"A1"`) |
+ */
+export declare const PluginSpreadsheetBindingTarget: z.ZodObject<{
+    sheetName: z.ZodString;
+    startCell: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginSpreadsheetBindingTarget = z.infer<typeof PluginSpreadsheetBindingTarget>;
+/**
+ * A stored data binding.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Binding id |
+ * | `name` | `string` | Binding name (unique per workbook) |
+ * | `pluginId` | `string` | Id of the plugin that owns the binding |
+ * | `source` | {@linkcode PluginSpreadsheetBindingSource} | The bound dataset |
+ * | `target` | `{ sheetName: string; startCell: string }` | The resolved target range anchor |
+ * | `mode` | {@linkcode PluginSpreadsheetBindingMode} | How a refresh writes into the target |
+ * | `createdAt` | `string` | ISO creation timestamp |
+ * | `updatedAt` | `string` | ISO last-refresh timestamp |
+ */
+export declare const PluginSpreadsheetBinding: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    pluginId: z.ZodString;
+    source: z.ZodObject<{
+        dataset: z.ZodEnum<{
+            takeoff: "takeoff";
+        }>;
+    }, z.core.$strip>;
+    target: z.ZodObject<{
+        sheetName: z.ZodString;
+        startCell: z.ZodString;
+    }, z.core.$strip>;
+    mode: z.ZodEnum<{
+        replaceRange: "replaceRange";
+    }>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type PluginSpreadsheetBinding = z.infer<typeof PluginSpreadsheetBinding>;
+/**
+ * The outcome of refreshing a single binding.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The refreshed binding's id |
+ * | `name` | `string` | The refreshed binding's name |
+ * | `sheetName` | `string` | The sheet that was rewritten |
+ * | `rowCount` | `number` | Number of rows written |
+ */
+export declare const PluginSpreadsheetBindingRefresh: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    sheetName: z.ZodString;
+    rowCount: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginSpreadsheetBindingRefresh = z.infer<typeof PluginSpreadsheetBindingRefresh>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetBindingsApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Binding name (re-using a name overwrites it) |
+ * | `source` | {@linkcode PluginSpreadsheetBindingSource} | The dataset to bind |
+ * | `target` | {@linkcode PluginSpreadsheetBindingTarget} | The target sheet range |
+ * | `mode` | {@linkcode PluginSpreadsheetBindingMode}`?` | How a refresh writes (default `"replaceRange"`) |
+ */
+export declare const PluginProgramSpreadsheetBindingsCreateArgs: z.ZodObject<{
+    name: z.ZodString;
+    source: z.ZodObject<{
+        dataset: z.ZodEnum<{
+            takeoff: "takeoff";
+        }>;
+    }, z.core.$strip>;
+    target: z.ZodObject<{
+        sheetName: z.ZodString;
+        startCell: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        replaceRange: "replaceRange";
+    }>>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetBindingsCreateArgs = z.infer<typeof PluginProgramSpreadsheetBindingsCreateArgs>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetBindingsApi.create} — the stored
+ * {@linkcode PluginSpreadsheetBinding} plus the initial `refresh` outcome.
+ */
+export declare const PluginProgramSpreadsheetBindingsCreateResult: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    pluginId: z.ZodString;
+    source: z.ZodObject<{
+        dataset: z.ZodEnum<{
+            takeoff: "takeoff";
+        }>;
+    }, z.core.$strip>;
+    target: z.ZodObject<{
+        sheetName: z.ZodString;
+        startCell: z.ZodString;
+    }, z.core.$strip>;
+    mode: z.ZodEnum<{
+        replaceRange: "replaceRange";
+    }>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    refresh: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        sheetName: z.ZodString;
+        rowCount: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetBindingsCreateResult = z.infer<typeof PluginProgramSpreadsheetBindingsCreateResult>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetBindingsApi.refresh}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string?` | The binding to refresh; omit to refresh every binding |
+ */
+export declare const PluginProgramSpreadsheetBindingsRefreshArgs: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetBindingsRefreshArgs = z.infer<typeof PluginProgramSpreadsheetBindingsRefreshArgs>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetBindingsApi.refresh}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `refreshed` | {@linkcode PluginSpreadsheetBindingRefresh}`[]` | One entry per binding refreshed |
+ */
+export declare const PluginProgramSpreadsheetBindingsRefreshResult: z.ZodObject<{
+    refreshed: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        sheetName: z.ZodString;
+        rowCount: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetBindingsRefreshResult = z.infer<typeof PluginProgramSpreadsheetBindingsRefreshResult>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetBindingsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `bindings` | {@linkcode PluginSpreadsheetBinding}`[]` | Every stored binding |
+ */
+export declare const PluginProgramSpreadsheetBindingsListResult: z.ZodObject<{
+    bindings: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        pluginId: z.ZodString;
+        source: z.ZodObject<{
+            dataset: z.ZodEnum<{
+                takeoff: "takeoff";
+            }>;
+        }, z.core.$strip>;
+        target: z.ZodObject<{
+            sheetName: z.ZodString;
+            startCell: z.ZodString;
+        }, z.core.$strip>;
+        mode: z.ZodEnum<{
+            replaceRange: "replaceRange";
+        }>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetBindingsListResult = z.infer<typeof PluginProgramSpreadsheetBindingsListResult>;
+//# sourceMappingURL=spreadsheet.d.ts.map