@snaptrude/plugin-core 0.2.9 → 0.5.0

package/src/api/program/spreadsheet.ts

@@ -0,0 +1,2075 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { PluginAreaUnit } from "./metrics"
+
+/**
+ * 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 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}.
+   */
+  public abstract templates: PluginProgramSpreadsheetTemplatesApi
+
+  /**
+   * Live data bindings — bind a program dataset to a sheet range and refresh it
+   * on demand. See {@linkcode PluginProgramSpreadsheetBindingsApi}.
+   */
+  public 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" }] },
+   * )
+   * ```
+   */
+  public 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" })
+   * ```
+   */
+  public 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" })
+   * ```
+   */
+  public 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
+   * ```
+   */
+  public 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()
+   * ```
+   */
+  public 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 },
+   * )
+   * ```
+   */
+  public 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" },
+   * )
+   * ```
+   */
+  public 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",
+   * })
+   * ```
+   */
+  public abstract highlightCells(
+    sheetName: string,
+    range: string,
+    options?: { color?: string; bold?: boolean },
+  ): PluginApiReturn<PluginProgramSpreadsheetHighlightCellsResult>
+
+  // --- Program / takeoff dataset reads (the data the render* methods draw) ---
+
+  /**
+   * 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)
+   * ```
+   */
+  public 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")
+   * ```
+   */
+  public abstract getTakeoff(): PluginApiReturn<PluginProgramSpreadsheetGetTakeoffResult>
+
+  // --- Sheet construction (lower-level cell writes; render is the high-level path) ---
+
+  /**
+   * 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")
+   * ```
+   */
+  public 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",
+   * )
+   * ```
+   */
+  public 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)" },
+   * ])
+   * ```
+   */
+  public abstract setFormulas(
+    sheetName: string,
+    formulas: PluginSpreadsheetFormula[],
+  ): PluginApiReturn<PluginProgramSpreadsheetSetFormulasResult>
+
+  // --- Formatting ---
+
+  /**
+   * 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" } },
+   * ])
+   * ```
+   */
+  public 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")
+   * ```
+   */
+  public 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",
+   * })
+   * ```
+   */
+  public abstract addConditionalFormatting(
+    sheetName: string,
+    range: string,
+    rule: PluginSpreadsheetConditionalRule,
+  ): PluginApiReturn<PluginProgramSpreadsheetAddConditionalFormattingResult>
+
+  // --- Recalculation & atomic batching ---
+
+  /**
+   * 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()
+   * ```
+   */
+  public 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",
+   * )
+   * ```
+   */
+  public abstract transaction(
+    operations: PluginSpreadsheetTransactionOp[],
+    label?: string,
+  ): PluginApiReturn<PluginProgramSpreadsheetTransactionResult>
+
+  // --- Meta: script escape hatch, audit log, liveness ---
+
+  /**
+   * 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();",
+   * )
+   * ```
+   */
+  public 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 })
+   * ```
+   */
+  public 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()
+   * ```
+   */
+  public 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 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")
+   * ```
+   */
+  public 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")
+   * ```
+   */
+  public 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 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" },
+   * )
+   * ```
+   */
+  public 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" })
+   * ```
+   */
+  public 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()
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginProgramSpreadsheetBindingsListResult>
+}
+
+/** A single spreadsheet cell value. */
+export const PluginSpreadsheetCell = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+])
+export type PluginSpreadsheetCell = z.infer<typeof PluginSpreadsheetCell>
+
+/** Horizontal alignment for a rendered column. */
+export const PluginSpreadsheetAlign = z.enum(["left", "center", "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 const PluginSpreadsheetColumn = z.object({
+  key: z.string(),
+  header: z.string(),
+  width: z.number().optional(),
+  format: z.string().optional(),
+  align: PluginSpreadsheetAlign.optional(),
+})
+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 const PluginSpreadsheetTotal = z.object({
+  column: z.string(),
+  fn: z.enum(["sum", "avg", "count", "min", "max"]),
+  label: z.string().optional(),
+})
+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 const PluginProgramSpreadsheetRenderArgs = z.object({
+  sheetName: z.string(),
+  columns: z.array(PluginSpreadsheetColumn),
+  rows: z.array(z.record(z.string(), PluginSpreadsheetCell)),
+  title: z.string().optional(),
+  startCell: z.string().optional(),
+  whenExists: z.enum(["replace", "error"]).optional(),
+  asTable: z.boolean().optional(),
+  freezeHeader: z.boolean().optional(),
+  totals: z.array(PluginSpreadsheetTotal).optional(),
+})
+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 const PluginProgramSpreadsheetRenderResult = z.object({
+  sheetName: z.string(),
+  range: z.string(),
+  headerRange: z.string(),
+  rowCount: z.number(),
+  colCount: z.number(),
+  tableName: z.string().nullable(),
+  replaced: z.boolean(),
+})
+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 const PluginProgramSpreadsheetRenderDatasetArgs = z.object({
+  sheetName: z.string().optional(),
+  title: z.string().optional(),
+  filter: z.string().optional(),
+})
+export type PluginProgramSpreadsheetRenderDatasetArgs = z.infer<
+  typeof PluginProgramSpreadsheetRenderDatasetArgs
+>
+
+/** The workbook export file format. */
+export const PluginSpreadsheetExportFormat = z.enum(["xlsx", "pdf", "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 const PluginProgramSpreadsheetExportArgs = z.object({
+  format: PluginSpreadsheetExportFormat,
+  fileName: z.string().optional(),
+})
+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 const PluginProgramSpreadsheetExportResult = z.object({
+  format: PluginSpreadsheetExportFormat,
+  fileName: z.string(),
+  mimeType: z.string(),
+  dataBase64: z.string(),
+})
+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 const PluginSpreadsheetSheetInfo = z.object({
+  name: z.string(),
+  index: z.number(),
+  visible: z.boolean(),
+  rowCount: z.number(),
+  colCount: z.number(),
+})
+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 const PluginProgramSpreadsheetListSheetsResult = z.object({
+  sheets: z.array(PluginSpreadsheetSheetInfo),
+  activeSheet: z.string().nullable(),
+})
+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 const PluginProgramSpreadsheetGetSheetDataArgs = z.object({
+  sheetName: z.string(),
+  range: z.string().optional(),
+  header: z.boolean().optional(),
+})
+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 const PluginProgramSpreadsheetGetSheetDataResult = z.object({
+  sheetName: z.string(),
+  range: z.string(),
+  values: z.array(z.array(PluginSpreadsheetCell)),
+  records: z.array(z.record(z.string(), PluginSpreadsheetCell)).optional(),
+})
+export type PluginProgramSpreadsheetGetSheetDataResult = z.infer<
+  typeof PluginProgramSpreadsheetGetSheetDataResult
+>
+
+/** Chart type for {@linkcode PluginProgramSpreadsheetApi.addChart}. */
+export const PluginSpreadsheetChartType = z.enum([
+  "column",
+  "bar",
+  "line",
+  "pie",
+  "area",
+  "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 const PluginProgramSpreadsheetAddChartArgs = z.object({
+  sheetName: z.string(),
+  chartType: PluginSpreadsheetChartType,
+  dataRange: z.string(),
+  title: z.string().optional(),
+  position: z.object({ x: z.number(), y: z.number() }).optional(),
+  size: z.object({ width: z.number(), height: z.number() }).optional(),
+})
+export type PluginProgramSpreadsheetAddChartArgs = z.infer<
+  typeof PluginProgramSpreadsheetAddChartArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.addChart}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `chartId` | `string` | Id of the created chart |
+ */
+export const PluginProgramSpreadsheetAddChartResult = z.object({
+  chartId: z.string(),
+})
+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 const PluginProgramSpreadsheetHighlightCellsArgs = z.object({
+  sheetName: z.string(),
+  range: z.string(),
+  color: z.string().optional(),
+  bold: z.boolean().optional(),
+})
+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 const PluginProgramSpreadsheetHighlightCellsResult = z.object({
+  sheetName: z.string(),
+  range: z.string(),
+})
+export type PluginProgramSpreadsheetHighlightCellsResult = z.infer<
+  typeof PluginProgramSpreadsheetHighlightCellsResult
+>
+
+// --- getProgram / getTakeoff dataset reads ---------------------------------
+
+/**
+ * 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 const PluginSpreadsheetProgramRow = z.object({
+  departmentId: z.string(),
+  name: z.string(),
+  targetArea: z.number().nullable(),
+  allocatedArea: z.number(),
+  variance: z.number().nullable(),
+})
+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 const PluginProgramSpreadsheetGetProgramResult = z.object({
+  units: PluginAreaUnit,
+  rows: z.array(PluginSpreadsheetProgramRow),
+  totalTargetArea: z.number(),
+  totalAllocatedArea: z.number(),
+  generatedAt: z.string(),
+})
+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 const PluginSpreadsheetTakeoffRow = z.object({
+  objectType: z.string(),
+  category: z.string(),
+  family: z.string(),
+  quantity: z.number(),
+  unit: z.string(),
+})
+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 const PluginProgramSpreadsheetGetTakeoffResult = z.object({
+  rows: z.array(PluginSpreadsheetTakeoffRow),
+  rowCount: z.number(),
+  generatedAt: z.string(),
+})
+export type PluginProgramSpreadsheetGetTakeoffResult = z.infer<
+  typeof PluginProgramSpreadsheetGetTakeoffResult
+>
+
+// --- createSheet -----------------------------------------------------------
+
+/** Behaviour when {@linkcode PluginProgramSpreadsheetApi.createSheet} targets an existing sheet name. */
+export const PluginSpreadsheetWhenExists = z.enum(["reuse", "replace", "error"])
+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 const PluginProgramSpreadsheetCreateSheetArgs = z.object({
+  name: z.string(),
+  whenExists: PluginSpreadsheetWhenExists.optional(),
+})
+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 const PluginProgramSpreadsheetCreateSheetResult = z.object({
+  sheetName: z.string(),
+  replaced: z.boolean(),
+  sheetIndex: z.number().nullable(),
+})
+export type PluginProgramSpreadsheetCreateSheetResult = z.infer<
+  typeof PluginProgramSpreadsheetCreateSheetResult
+>
+
+// --- setValues -------------------------------------------------------------
+
+/**
+ * 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 const PluginProgramSpreadsheetSetValuesArgs = z.object({
+  sheetName: z.string(),
+  values: z.array(z.array(PluginSpreadsheetCell)),
+  startCell: z.string().optional(),
+})
+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 const PluginProgramSpreadsheetSetValuesResult = z.object({
+  sheetName: z.string(),
+  startCell: z.string(),
+  rowCount: z.number(),
+  colCount: z.number(),
+})
+export type PluginProgramSpreadsheetSetValuesResult = z.infer<
+  typeof PluginProgramSpreadsheetSetValuesResult
+>
+
+// --- setFormulas -----------------------------------------------------------
+
+/**
+ * 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 const PluginSpreadsheetFormula = z.object({
+  cell: z.string(),
+  formula: z.string(),
+})
+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 const PluginProgramSpreadsheetSetFormulasArgs = z.object({
+  sheetName: z.string(),
+  formulas: z.array(PluginSpreadsheetFormula),
+})
+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 const PluginProgramSpreadsheetSetFormulasResult = z.object({
+  sheetName: z.string(),
+  count: z.number(),
+})
+export type PluginProgramSpreadsheetSetFormulasResult = z.infer<
+  typeof PluginProgramSpreadsheetSetFormulasResult
+>
+
+// --- setStyles -------------------------------------------------------------
+
+/** Font weight for a {@linkcode PluginSpreadsheetCellStyle}. */
+export const PluginSpreadsheetFontWeight = z.enum(["normal", "bold"])
+export type PluginSpreadsheetFontWeight = z.infer<
+  typeof PluginSpreadsheetFontWeight
+>
+
+/** Font style for a {@linkcode PluginSpreadsheetCellStyle}. */
+export const PluginSpreadsheetFontStyle = z.enum(["normal", "italic"])
+export type PluginSpreadsheetFontStyle = z.infer<
+  typeof PluginSpreadsheetFontStyle
+>
+
+/** Horizontal cell alignment for a {@linkcode PluginSpreadsheetCellStyle}. */
+export const PluginSpreadsheetHorizontalAlign = z.enum([
+  "left",
+  "center",
+  "right",
+  "general",
+])
+export type PluginSpreadsheetHorizontalAlign = z.infer<
+  typeof PluginSpreadsheetHorizontalAlign
+>
+
+/** Vertical cell alignment for a {@linkcode PluginSpreadsheetCellStyle}. */
+export const PluginSpreadsheetVerticalAlign = z.enum([
+  "top",
+  "center",
+  "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 const PluginSpreadsheetCellStyle = z.object({
+  backColor: z.string().optional(),
+  foreColor: z.string().optional(),
+  font: z.string().optional(),
+  fontFamily: z.string().optional(),
+  fontSize: z.number().optional(),
+  fontWeight: PluginSpreadsheetFontWeight.optional(),
+  fontStyle: PluginSpreadsheetFontStyle.optional(),
+  formatter: z.string().optional(),
+  horizontalAlign: PluginSpreadsheetHorizontalAlign.optional(),
+  verticalAlign: PluginSpreadsheetVerticalAlign.optional(),
+})
+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 const PluginSpreadsheetRangeStyle = z.object({
+  range: z.string(),
+  style: PluginSpreadsheetCellStyle,
+})
+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 const PluginProgramSpreadsheetSetStylesArgs = z.object({
+  sheetName: z.string(),
+  ranges: z.array(PluginSpreadsheetRangeStyle),
+})
+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 const PluginProgramSpreadsheetSetStylesResult = z.object({
+  sheetName: z.string(),
+  count: z.number(),
+})
+export type PluginProgramSpreadsheetSetStylesResult = z.infer<
+  typeof PluginProgramSpreadsheetSetStylesResult
+>
+
+// --- mergeCells ------------------------------------------------------------
+
+/**
+ * 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 const PluginProgramSpreadsheetMergeCellsArgs = z.object({
+  sheetName: z.string(),
+  range: z.string(),
+  value: PluginSpreadsheetCell.optional(),
+})
+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 const PluginProgramSpreadsheetMergeCellsResult = z.object({
+  sheetName: z.string(),
+  range: z.string(),
+})
+export type PluginProgramSpreadsheetMergeCellsResult = z.infer<
+  typeof PluginProgramSpreadsheetMergeCellsResult
+>
+
+// --- addConditionalFormatting ----------------------------------------------
+
+/** Conditional-formatting rule type. Currently only `dataBar`; more are reserved. */
+export const PluginSpreadsheetConditionalRuleType = z.enum(["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 const PluginSpreadsheetConditionalRule = z.object({
+  type: PluginSpreadsheetConditionalRuleType,
+  color: z.string().optional(),
+})
+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 const PluginProgramSpreadsheetAddConditionalFormattingArgs = z.object({
+  sheetName: z.string(),
+  range: z.string(),
+  rule: PluginSpreadsheetConditionalRule,
+})
+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 const PluginProgramSpreadsheetAddConditionalFormattingResult = z.object({
+  sheetName: z.string(),
+  range: z.string(),
+  created: z.boolean(),
+})
+export type PluginProgramSpreadsheetAddConditionalFormattingResult = z.infer<
+  typeof PluginProgramSpreadsheetAddConditionalFormattingResult
+>
+
+// --- recalculate -----------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.recalculate}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string?` | A sheet to focus before recalculating; omit for the whole workbook |
+ */
+export const PluginProgramSpreadsheetRecalculateArgs = z.object({
+  sheetName: z.string().optional(),
+})
+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 const PluginProgramSpreadsheetRecalculateResult = z.object({
+  scope: z.enum(["sheet", "workbook"]),
+  sheetName: z.string().nullable(),
+})
+export type PluginProgramSpreadsheetRecalculateResult = z.infer<
+  typeof PluginProgramSpreadsheetRecalculateResult
+>
+
+// --- transaction -----------------------------------------------------------
+
+/** A batchable operation name for {@linkcode PluginProgramSpreadsheetApi.transaction}. */
+export const PluginSpreadsheetTransactionMethod = z.enum([
+  "createSheet",
+  "setValues",
+  "setFormulas",
+  "setStyles",
+  "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 const PluginSpreadsheetTransactionOp = z.object({
+  method: PluginSpreadsheetTransactionMethod,
+  args: z.unknown(),
+})
+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 const PluginProgramSpreadsheetTransactionArgs = z.object({
+  operations: z.array(PluginSpreadsheetTransactionOp),
+  label: z.string().optional(),
+})
+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 const PluginProgramSpreadsheetTransactionResult = z.object({
+  label: z.string(),
+  operationCount: z.number(),
+  results: z.array(z.unknown()),
+})
+export type PluginProgramSpreadsheetTransactionResult = z.infer<
+  typeof PluginProgramSpreadsheetTransactionResult
+>
+
+// --- runScript -------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.runScript}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `script` | `string` | Script source, run against a sandboxed `workbook` facade |
+ */
+export const PluginProgramSpreadsheetRunScriptArgs = z.object({
+  script: z.string(),
+})
+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 const PluginProgramSpreadsheetRunScriptResult = z.object({
+  result: z.unknown(),
+})
+export type PluginProgramSpreadsheetRunScriptResult = z.infer<
+  typeof PluginProgramSpreadsheetRunScriptResult
+>
+
+// --- getAuditLog -----------------------------------------------------------
+
+/** Status of an audit-log entry. */
+export const PluginSpreadsheetAuditStatus = z.enum(["success", "error"])
+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 const PluginSpreadsheetAuditEntry = z.object({
+  id: z.string(),
+  pluginId: z.string(),
+  method: z.string(),
+  label: z.string().optional(),
+  sheetName: z.string().optional(),
+  timestamp: z.string(),
+  status: PluginSpreadsheetAuditStatus,
+  summary: z.string().optional(),
+})
+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 const PluginProgramSpreadsheetGetAuditLogArgs = z.object({
+  limit: z.number().optional(),
+})
+export type PluginProgramSpreadsheetGetAuditLogArgs = z.infer<
+  typeof PluginProgramSpreadsheetGetAuditLogArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.getAuditLog}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `entries` | {@linkcode PluginSpreadsheetAuditEntry}`[]` | Recent audit entries, newest first |
+ */
+export const PluginProgramSpreadsheetGetAuditLogResult = z.object({
+  entries: z.array(PluginSpreadsheetAuditEntry),
+})
+export type PluginProgramSpreadsheetGetAuditLogResult = z.infer<
+  typeof PluginProgramSpreadsheetGetAuditLogResult
+>
+
+// --- ping ------------------------------------------------------------------
+
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.ping}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `pong` | `boolean` | `true` when the program-mode spreadsheet bridge is reachable |
+ */
+export const PluginProgramSpreadsheetPingResult = z.object({
+  pong: z.boolean(),
+})
+export type PluginProgramSpreadsheetPingResult = z.infer<
+  typeof PluginProgramSpreadsheetPingResult
+>
+
+// --- templates.* -----------------------------------------------------------
+
+/** The visibility scope of a saved template. */
+export const PluginSpreadsheetTemplateScope = z.enum(["project", "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 const PluginProgramSpreadsheetTemplatesCreateArgs = z.object({
+  name: z.string(),
+  sheetName: z.string(),
+  scope: PluginSpreadsheetTemplateScope.optional(),
+})
+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 const PluginProgramSpreadsheetTemplatesCreateResult = z.object({
+  id: z.string(),
+  name: z.string(),
+  scope: PluginSpreadsheetTemplateScope,
+  sheetName: z.string(),
+})
+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 const PluginProgramSpreadsheetTemplatesApplyArgs = z.object({
+  name: z.string(),
+  targetSheetName: z.string(),
+})
+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 const PluginProgramSpreadsheetTemplatesApplyResult = z.object({
+  name: z.string(),
+  targetSheetName: z.string(),
+})
+export type PluginProgramSpreadsheetTemplatesApplyResult = z.infer<
+  typeof PluginProgramSpreadsheetTemplatesApplyResult
+>
+
+// --- bindings.* ------------------------------------------------------------
+
+/**
+ * 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 const PluginSpreadsheetBindingSource = z.object({
+  dataset: z.enum(["takeoff"]),
+})
+export type PluginSpreadsheetBindingSource = z.infer<
+  typeof PluginSpreadsheetBindingSource
+>
+
+/** How a binding refresh writes into its target range. Currently only `replaceRange`. */
+export const PluginSpreadsheetBindingMode = z.enum(["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 const PluginSpreadsheetBindingTarget = z.object({
+  sheetName: z.string(),
+  startCell: z.string().optional(),
+})
+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 const PluginSpreadsheetBinding = z.object({
+  id: z.string(),
+  name: z.string(),
+  pluginId: z.string(),
+  source: PluginSpreadsheetBindingSource,
+  target: z.object({
+    sheetName: z.string(),
+    startCell: z.string(),
+  }),
+  mode: PluginSpreadsheetBindingMode,
+  createdAt: z.string(),
+  updatedAt: z.string(),
+})
+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 const PluginSpreadsheetBindingRefresh = z.object({
+  id: z.string(),
+  name: z.string(),
+  sheetName: z.string(),
+  rowCount: z.number(),
+})
+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 const PluginProgramSpreadsheetBindingsCreateArgs = z.object({
+  name: z.string(),
+  source: PluginSpreadsheetBindingSource,
+  target: PluginSpreadsheetBindingTarget,
+  mode: PluginSpreadsheetBindingMode.optional(),
+})
+export type PluginProgramSpreadsheetBindingsCreateArgs = z.infer<
+  typeof PluginProgramSpreadsheetBindingsCreateArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetBindingsApi.create} — the stored
+ * {@linkcode PluginSpreadsheetBinding} plus the initial `refresh` outcome.
+ */
+export const PluginProgramSpreadsheetBindingsCreateResult =
+  PluginSpreadsheetBinding.extend({
+    refresh: PluginSpreadsheetBindingRefresh,
+  })
+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 const PluginProgramSpreadsheetBindingsRefreshArgs = z.object({
+  name: z.string().optional(),
+})
+export type PluginProgramSpreadsheetBindingsRefreshArgs = z.infer<
+  typeof PluginProgramSpreadsheetBindingsRefreshArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetBindingsApi.refresh}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `refreshed` | {@linkcode PluginSpreadsheetBindingRefresh}`[]` | One entry per binding refreshed |
+ */
+export const PluginProgramSpreadsheetBindingsRefreshResult = z.object({
+  refreshed: z.array(PluginSpreadsheetBindingRefresh),
+})
+export type PluginProgramSpreadsheetBindingsRefreshResult = z.infer<
+  typeof PluginProgramSpreadsheetBindingsRefreshResult
+>
+
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetBindingsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `bindings` | {@linkcode PluginSpreadsheetBinding}`[]` | Every stored binding |
+ */
+export const PluginProgramSpreadsheetBindingsListResult = z.object({
+  bindings: z.array(PluginSpreadsheetBinding),
+})
+export type PluginProgramSpreadsheetBindingsListResult = z.infer<
+  typeof PluginProgramSpreadsheetBindingsListResult
+>