@snaptrude/plugin-core 0.7.1 → 0.9.0

package/src/api/program/spreadsheet.ts

@@ -23,7 +23,8 @@ import { PluginAreaUnit } from "./metrics"
  *
  * Plus dataset reads ({@linkcode PluginProgramSpreadsheetApi.getProgram} /
  * {@linkcode PluginProgramSpreadsheetApi.getTakeoff} — the data the render* methods
- * draw), sheet reads ({@linkcode PluginProgramSpreadsheetApi.listSheets} /
+ * draw — and {@linkcode PluginProgramSpreadsheetApi.getMaterialTakeoff}, surface area
+ * per material), sheet reads ({@linkcode PluginProgramSpreadsheetApi.listSheets} /
  * {@linkcode PluginProgramSpreadsheetApi.getSheetData}), charts + emphasis
  * ({@linkcode PluginProgramSpreadsheetApi.addChart} /
  * {@linkcode PluginProgramSpreadsheetApi.highlightCells}), workbook file export
@@ -67,6 +68,12 @@ export abstract class PluginProgramSpreadsheetApi {
    */
   public abstract bindings: PluginProgramSpreadsheetBindingsApi
 
+  /**
+   * Plugin datasets — named, plugin-supplied row sets that bindings can render
+   * and auto-refresh on rerun. See {@linkcode PluginProgramSpreadsheetDatasetsApi}.
+   */
+  public abstract datasets: PluginProgramSpreadsheetDatasetsApi
+
   /**
    * Render a titled, formatted table onto a named sheet (create-or-replace).
    *
@@ -128,13 +135,15 @@ export abstract class PluginProgramSpreadsheetApi {
    * 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
+   * data argument**. The `filter` is applied host-side to the projected rows
+   * before rendering. 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}).
+   * @param options - Optional `sheetName`, `title`, and `filter` — a
+   *   case-insensitive substring kept when any of a row's cell values contains
+   *   it (a {@linkcode PluginProgramSpreadsheetRenderDatasetArgs}).
    * @returns A {@linkcode PluginProgramSpreadsheetRenderResult} with the written
    *   ranges and counts.
    * @throws If the takeoff cannot be rendered.
@@ -149,9 +158,11 @@ export abstract class PluginProgramSpreadsheetApi {
    * await snaptrude.program.spreadsheet.renderTakeoff({ sheetName: "Takeoff" })
    * ```
    */
-  public abstract renderTakeoff(
-    options?: { sheetName?: string; title?: string; filter?: string },
-  ): PluginApiReturn<PluginProgramSpreadsheetRenderResult>
+  public abstract renderTakeoff(options?: {
+    sheetName?: string
+    title?: string
+    filter?: string
+  }): PluginApiReturn<PluginProgramSpreadsheetRenderResult>
 
   /**
    * Render the area program onto a sheet.
@@ -159,13 +170,15 @@ export abstract class PluginProgramSpreadsheetApi {
    * 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
+   * optional `filter`; there is **no data argument**. The `filter` is applied
+   * host-side to the projected rows before rendering. 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}).
+   * @param options - Optional `sheetName`, `title`, and `filter` — a
+   *   case-insensitive substring kept when any of a row's cell values contains
+   *   it (a {@linkcode PluginProgramSpreadsheetRenderDatasetArgs}).
    * @returns A {@linkcode PluginProgramSpreadsheetRenderResult} with the written
    *   ranges and counts.
    * @throws If the program cannot be rendered.
@@ -180,20 +193,30 @@ export abstract class PluginProgramSpreadsheetApi {
    * await snaptrude.program.spreadsheet.renderProgram({ sheetName: "Program" })
    * ```
    */
-  public abstract renderProgram(
-    options?: { sheetName?: string; title?: string; filter?: string },
-  ): PluginApiReturn<PluginProgramSpreadsheetRenderResult>
+  public abstract renderProgram(options?: {
+    sheetName?: string
+    title?: string
+    filter?: string
+  }): PluginApiReturn<PluginProgramSpreadsheetRenderResult>
 
   /**
-   * Export the whole report workbook to a file (xlsx, pdf, or csv).
+   * Export the 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.
+   * `xlsx` and `pdf` export the **whole** workbook. `csv` is inherently
+   * single-sheet: it serializes one sheet's used range — pass `options.sheetName`
+   * to choose which sheet, or omit it to serialize the active sheet.
+   *
+   * For a different export intent, see `core.io.export.model` (the 3D model
+   * file) and `presentation.export` (Present-mode layout sheets to PDF/PNG/JPG).
+   *
+   * @param format - The file format to export to.
+   * @param options - Optional `fileName` (without extension; a default is used
+   *   when omitted) and `sheetName` — the sheet to serialize for `csv`
+   *   (ignored by `xlsx`/`pdf`, which always export the whole workbook).
    * @returns A {@linkcode PluginProgramSpreadsheetExportResult} with the file's
    *   `fileName`, `mimeType`, and base64 `dataBase64`.
    * @throws If the workbook cannot be serialized to the requested format.
@@ -202,16 +225,20 @@ export abstract class PluginProgramSpreadsheetApi {
    * @examplePrompt Download the whole workbook as a PDF
    * @examplePrompt Export the program workbook to xlsx
    * @examplePrompt Save the report as a csv file
+   * @examplePrompt Export the Takeoff sheet as CSV
    *
    * # Example
    * ```ts
    * const file = await snaptrude.program.spreadsheet.export("xlsx")
    * // file.fileName, file.mimeType, file.dataBase64
+   *
+   * // CSV of a specific sheet:
+   * const csv = await snaptrude.program.spreadsheet.export("csv", { sheetName: "Takeoff" })
    * ```
    */
   public abstract export(
     format: PluginSpreadsheetExportFormat,
-    options?: { fileName?: string },
+    options?: { fileName?: string; sheetName?: string },
   ): PluginApiReturn<PluginProgramSpreadsheetExportResult>
 
   /**
@@ -297,6 +324,55 @@ export abstract class PluginProgramSpreadsheetApi {
     },
   ): PluginApiReturn<PluginProgramSpreadsheetAddChartResult>
 
+  /**
+   * Place a floating image on a workbook sheet from a base64 data URI.
+   *
+   * The image is anchored at a cell's top-left corner (default `"A1"`) and
+   * floats over the grid (a SpreadJS floating picture — it does not occupy
+   * cells). Only base64 `data:image/png|jpeg|svg+xml` URIs are accepted —
+   * never URLs — and the URI is capped at 2 MB. Passing a `name` gives the
+   * picture a stable id: re-running with the same `name` replaces the previous
+   * picture (rerun-friendly); when omitted a name is generated.
+   *
+   * For images on Present-mode sheets (the tldraw canvas), use
+   * `presentation.shapes` instead — this verb places floating pictures in the
+   * SpreadJS workbook.
+   *
+   * @param sheetName - Sheet to place the image on.
+   * @param image - The image payload: a base64 `dataUri`
+   *   (`data:image/png|jpeg|svg+xml;base64,…`, max 2 MB).
+   * @param options - Optional `anchorCell` (A1 notation, default `"A1"`),
+   *   `size` in px (intrinsic size when omitted), and stable `name`
+   *   (replace-on-rerun).
+   * @returns A {@linkcode PluginProgramSpreadsheetAddImageResult} with the sheet
+   *   and the picture's name.
+   * @throws If the sheet does not exist, or the data URI is not an accepted
+   *   image type or exceeds 2 MB.
+   *
+   * @examplePrompt Add my logo image to the report sheet
+   * @examplePrompt Place a PNG at cell B2 on the Takeoff sheet
+   * @examplePrompt Put an SVG diagram on a spreadsheet sheet
+   * @examplePrompt Insert an image into the workbook
+   *
+   * # Example
+   * ```ts
+   * const { name } = await snaptrude.program.spreadsheet.addImage(
+   *   "Report",
+   *   { dataUri: "data:image/png;base64,iVBORw0..." },
+   *   { anchorCell: "B2", size: { width: 240, height: 120 }, name: "logo" },
+   * )
+   * ```
+   */
+  public abstract addImage(
+    sheetName: string,
+    image: { dataUri: string },
+    options?: {
+      anchorCell?: string
+      size?: { width: number; height: number }
+      name?: string
+    },
+  ): PluginApiReturn<PluginProgramSpreadsheetAddImageResult>
+
   /**
    * Highlight a range of cells (background color and optional emphasis).
    *
@@ -378,6 +454,38 @@ export abstract class PluginProgramSpreadsheetApi {
    */
   public abstract getTakeoff(): PluginApiReturn<PluginProgramSpreadsheetGetTakeoffResult>
 
+  /**
+   * Read the material take-off dataset (surface area per material, per element type).
+   *
+   * The native "Material Take-Off" quantities — the same figures the BIM Take-Off's
+   * *Material Take-Off* sheet lists — as render-ready rows: for each material applied
+   * to a wall/floor/ceiling/slab/roof family, its rolled-up **surface area** in the
+   * project's display units. This is the material-centric complement to
+   * {@linkcode PluginProgramSpreadsheetApi.getTakeoff} (which rolls up by element
+   * family). A read only — nothing is written and no file is downloaded.
+   *
+   * When no materials are applied (or the model is empty) the result is simply an
+   * empty `rows` array — not an error.
+   *
+   * @returns A {@linkcode PluginProgramSpreadsheetGetMaterialTakeoffResult} with the
+   *   material take-off `rows`, a `rowCount`, and the `generatedAt` timestamp.
+   *
+   * @examplePrompt Get the material take-off
+   * @examplePrompt How much of each material is used?
+   * @examplePrompt Read the surface area by material
+   * @examplePrompt Give me the material quantities before I render them
+   * @examplePrompt What's in the material take-off right now?
+   *
+   * # Example
+   * ```ts
+   * const mto = await snaptrude.program.spreadsheet.getMaterialTakeoff()
+   * for (const row of mto.rows) {
+   *   console.log(row.objectType, row.family, row.material, row.quantity, row.unit)
+   * }
+   * ```
+   */
+  public abstract getMaterialTakeoff(): PluginApiReturn<PluginProgramSpreadsheetGetMaterialTakeoffResult>
+
   // --- Sheet construction (lower-level cell writes; render is the high-level path) ---
 
   /**
@@ -597,9 +705,9 @@ export abstract class PluginProgramSpreadsheetApi {
    * await snaptrude.program.spreadsheet.recalculate()
    * ```
    */
-  public abstract recalculate(
-    options?: { sheetName?: string },
-  ): PluginApiReturn<PluginProgramSpreadsheetRecalculateResult>
+  public abstract recalculate(options?: {
+    sheetName?: string
+  }): PluginApiReturn<PluginProgramSpreadsheetRecalculateResult>
 
   /**
    * Run a sequence of sheet operations as one atomic, undoable transaction.
@@ -689,9 +797,9 @@ export abstract class PluginProgramSpreadsheetApi {
    * const { entries } = await snaptrude.program.spreadsheet.getAuditLog({ limit: 10 })
    * ```
    */
-  public abstract getAuditLog(
-    options?: { limit?: number },
-  ): PluginApiReturn<PluginProgramSpreadsheetGetAuditLogResult>
+  public abstract getAuditLog(options?: {
+    limit?: number
+  }): PluginApiReturn<PluginProgramSpreadsheetGetAuditLogResult>
 
   /**
    * Ping the program-mode spreadsheet bridge to check it is reachable.
@@ -839,9 +947,9 @@ export abstract class PluginProgramSpreadsheetBindingsApi {
    * await snaptrude.program.spreadsheet.bindings.refresh({ name: "takeoff" })
    * ```
    */
-  public abstract refresh(
-    options?: { name?: string },
-  ): PluginApiReturn<PluginProgramSpreadsheetBindingsRefreshResult>
+  public abstract refresh(options?: {
+    name?: string
+  }): PluginApiReturn<PluginProgramSpreadsheetBindingsRefreshResult>
 
   /**
    * List all data bindings in the workbook.
@@ -861,6 +969,76 @@ export abstract class PluginProgramSpreadsheetBindingsApi {
   public abstract list(): PluginApiReturn<PluginProgramSpreadsheetBindingsListResult>
 }
 
+/**
+ * Program-spreadsheet plugin datasets — named, plugin-supplied row sets stored
+ * alongside the workbook so bindings can render and re-render them.
+ *
+ * A dataset is uploaded with {@linkcode PluginProgramSpreadsheetDatasetsApi.set}
+ * (upsert by name). A binding whose source is `{ dataset: "plugin", name }`
+ * renders the dataset at its target anchor, and re-renders automatically every
+ * time the dataset is set again — the "refresh on rerun" behaviour. Accessed
+ * via `snaptrude.program.spreadsheet.datasets`.
+ */
+export abstract class PluginProgramSpreadsheetDatasetsApi {
+  constructor() {}
+
+  /**
+   * Store (upsert) a named plugin dataset.
+   *
+   * Re-using a `name` replaces the dataset and automatically refreshes every
+   * binding whose source is `{ dataset: "plugin", name }` — no extra plugin
+   * calls needed to keep bound ranges current. Limits: at most 10,000 rows and
+   * 2 MB serialized.
+   *
+   * @param name - Dataset name (re-using a name overwrites it).
+   * @param columns - Column definitions (see {@linkcode PluginSpreadsheetColumn});
+   *   their order is the column order bindings render.
+   * @param rows - Row objects keyed by column `key`.
+   * @returns A {@linkcode PluginProgramSpreadsheetDatasetsSetResult} with the
+   *   stored row count.
+   * @throws If the dataset exceeds 10,000 rows or 2 MB serialized.
+   *
+   * @examplePrompt Store my plugin's rows as a named dataset
+   * @examplePrompt Upload data the sheets can bind to and refresh
+   * @examplePrompt Save a dataset for a live sheet binding
+   * @examplePrompt Push my computed table so a binding keeps it fresh
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.spreadsheet.datasets.set(
+   *   "costs",
+   *   [
+   *     { key: "item", header: "Item" },
+   *     { key: "cost", header: "Cost", align: "right" },
+   *   ],
+   *   [{ item: "Concrete", cost: 120 }],
+   * )
+   * ```
+   */
+  public abstract set(
+    name: string,
+    columns: PluginSpreadsheetColumn[],
+    rows: Record<string, PluginSpreadsheetCell>[],
+  ): PluginApiReturn<PluginProgramSpreadsheetDatasetsSetResult>
+
+  /**
+   * List the stored plugin datasets.
+   *
+   * @returns A {@linkcode PluginProgramSpreadsheetDatasetsListResult} with each
+   *   dataset's `name`, `rowCount`, and `updatedAt` timestamp.
+   *
+   * @examplePrompt List my plugin datasets
+   * @examplePrompt What datasets are stored for the sheets?
+   * @examplePrompt Show the data sets bindings can use
+   *
+   * # Example
+   * ```ts
+   * const { datasets } = await snaptrude.program.spreadsheet.datasets.list()
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginProgramSpreadsheetDatasetsListResult>
+}
+
 /** A single spreadsheet cell value. */
 export const PluginSpreadsheetCell = z.union([
   z.string(),
@@ -977,7 +1155,7 @@ export type PluginProgramSpreadsheetRenderResult = z.infer<
  * |---|---|---|
  * | `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 |
+ * | `filter` | `string?` | Case-insensitive substring — a row is kept when any of its cell values contains it (blank/omitted keeps every row). Not a query language. |
  */
 export const PluginProgramSpreadsheetRenderDatasetArgs = z.object({
   sheetName: z.string().optional(),
@@ -999,12 +1177,14 @@ export type PluginSpreadsheetExportFormat = z.infer<
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `format` | `"xlsx" \| "pdf" \| "csv"` | The file format to export the workbook to |
+ * | `format` | `"xlsx" \| "pdf" \| "csv"` | The file format to export to |
  * | `fileName` | `string?` | Desired file name (without extension); a default is used when omitted |
+ * | `sheetName` | `string?` | For `csv`: the sheet to serialize (the active sheet when omitted). Ignored by `xlsx`/`pdf`. |
  */
 export const PluginProgramSpreadsheetExportArgs = z.object({
   format: PluginSpreadsheetExportFormat,
   fileName: z.string().optional(),
+  sheetName: z.string().optional(),
 })
 export type PluginProgramSpreadsheetExportArgs = z.infer<
   typeof PluginProgramSpreadsheetExportArgs
@@ -1286,6 +1466,50 @@ export type PluginProgramSpreadsheetGetTakeoffResult = z.infer<
   typeof PluginProgramSpreadsheetGetTakeoffResult
 >
 
+/**
+ * One row in the material take-off dataset. The take-off is grouped by element
+ * object type + family + applied material, so each row is a rolled-up surface
+ * area for that material on that family.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `objectType` | `string` | Element object type the material sits on (`"wall"`, `"floor"`, `"ceiling"`, `"slab"`, `"roof"`) |
+ * | `family` | `string` | Element family the quantity is aggregated under |
+ * | `material` | `string` | Applied material name |
+ * | `quantity` | `number` | Rolled-up surface area in `unit` |
+ * | `unit` | `string` | Area unit (e.g. `"sq.ft"` or `"sq.m"`) |
+ */
+export const PluginSpreadsheetMaterialTakeoffRow = z.object({
+  objectType: z.string(),
+  family: z.string(),
+  material: z.string(),
+  quantity: z.number(),
+  unit: z.string(),
+})
+export type PluginSpreadsheetMaterialTakeoffRow = z.infer<
+  typeof PluginSpreadsheetMaterialTakeoffRow
+>
+
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.getMaterialTakeoff} — the native
+ * material take-off dataset (surface area per material). Empty when no materials are
+ * applied.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `rows` | {@linkcode PluginSpreadsheetMaterialTakeoffRow}`[]` | One row per object-type/family/material group |
+ * | `rowCount` | `number` | Number of rows |
+ * | `generatedAt` | `string` | ISO timestamp of when the dataset was read |
+ */
+export const PluginProgramSpreadsheetGetMaterialTakeoffResult = z.object({
+  rows: z.array(PluginSpreadsheetMaterialTakeoffRow),
+  rowCount: z.number(),
+  generatedAt: z.string(),
+})
+export type PluginProgramSpreadsheetGetMaterialTakeoffResult = z.infer<
+  typeof PluginProgramSpreadsheetGetMaterialTakeoffResult
+>
+
 // --- createSheet -----------------------------------------------------------
 
 /** Behaviour when {@linkcode PluginProgramSpreadsheetApi.createSheet} targets an existing sheet name. */
@@ -1915,16 +2139,18 @@ export type PluginProgramSpreadsheetTemplatesApplyResult = z.infer<
 // --- bindings.* ------------------------------------------------------------
 
 /**
- * A binding's data source. Currently only the takeoff dataset; `program` is
- * reserved for a future source.
+ * A binding's data source — the built-in takeoff dataset, or a named plugin
+ * dataset stored via {@linkcode PluginProgramSpreadsheetDatasetsApi.set}.
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `dataset` | `"takeoff"` | The dataset the binding pulls from |
+ * | `dataset` | `"takeoff" \| "plugin"` | The dataset kind the binding pulls from |
+ * | `name` | `string` | (`"plugin"` only) The stored dataset's name |
  */
-export const PluginSpreadsheetBindingSource = z.object({
-  dataset: z.enum(["takeoff"]),
-})
+export const PluginSpreadsheetBindingSource = z.discriminatedUnion("dataset", [
+  z.object({ dataset: z.literal("takeoff") }),
+  z.object({ dataset: z.literal("plugin"), name: z.string() }),
+])
 export type PluginSpreadsheetBindingSource = z.infer<
   typeof PluginSpreadsheetBindingSource
 >
@@ -2073,3 +2299,118 @@ export const PluginProgramSpreadsheetBindingsListResult = z.object({
 export type PluginProgramSpreadsheetBindingsListResult = z.infer<
   typeof PluginProgramSpreadsheetBindingsListResult
 >
+
+// --- datasets.* ------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetDatasetsApi.set}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Dataset name (re-using a name overwrites it) |
+ * | `columns` | {@linkcode PluginSpreadsheetColumn}`[]` | Column definitions (at least one) |
+ * | `rows` | `Record<string, cell>[]` | Row objects keyed by column `key` (max 10,000) |
+ */
+export const PluginProgramSpreadsheetDatasetsSetArgs = z.object({
+  name: z.string(),
+  columns: z.array(PluginSpreadsheetColumn).min(1),
+  rows: z.array(z.record(z.string(), PluginSpreadsheetCell)).max(10_000),
+})
+export type PluginProgramSpreadsheetDatasetsSetArgs = z.infer<
+  typeof PluginProgramSpreadsheetDatasetsSetArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetDatasetsApi.set}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | The stored dataset's name |
+ * | `rowCount` | `number` | Number of rows stored |
+ */
+export const PluginProgramSpreadsheetDatasetsSetResult = z.object({
+  name: z.string(),
+  rowCount: z.number(),
+})
+export type PluginProgramSpreadsheetDatasetsSetResult = z.infer<
+  typeof PluginProgramSpreadsheetDatasetsSetResult
+>
+
+/**
+ * A stored plugin dataset's summary, for
+ * {@linkcode PluginProgramSpreadsheetDatasetsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Dataset name |
+ * | `rowCount` | `number` | Number of rows stored |
+ * | `updatedAt` | `string` | ISO timestamp of the last `set` |
+ */
+export const PluginSpreadsheetDataset = z.object({
+  name: z.string(),
+  rowCount: z.number(),
+  updatedAt: z.string(),
+})
+export type PluginSpreadsheetDataset = z.infer<typeof PluginSpreadsheetDataset>
+
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetDatasetsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `datasets` | {@linkcode PluginSpreadsheetDataset}`[]` | Every stored dataset |
+ */
+export const PluginProgramSpreadsheetDatasetsListResult = z.object({
+  datasets: z.array(PluginSpreadsheetDataset),
+})
+export type PluginProgramSpreadsheetDatasetsListResult = z.infer<
+  typeof PluginProgramSpreadsheetDatasetsListResult
+>
+
+// --- addImage --------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.addImage}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | Sheet to place the image on |
+ * | `image` | `{ dataUri: string }` | Base64 `data:image/png\|jpeg\|svg+xml` URI (max 2 MB; URLs rejected) |
+ * | `anchorCell` | `string?` | Anchor cell in A1 notation (default `"A1"`) |
+ * | `size` | `{ width; height }?` | Size in px; intrinsic size when omitted |
+ * | `name` | `string?` | Stable picture id — same name replaces on rerun; generated when omitted |
+ */
+export const PluginProgramSpreadsheetAddImageArgs = z.object({
+  sheetName: z.string(),
+  image: z.object({
+    dataUri: z
+      .string()
+      .max(2_097_152, "image.dataUri exceeds the 2 MB limit")
+      .regex(
+        /^data:image\/(png|jpeg|svg\+xml);base64,/,
+        "image.dataUri must be a base64 data:image/png, jpeg, or svg+xml URI",
+      ),
+  }),
+  anchorCell: z.string().optional(),
+  size: z.object({ width: z.number(), height: z.number() }).optional(),
+  name: z.string().optional(),
+})
+export type PluginProgramSpreadsheetAddImageArgs = z.infer<
+  typeof PluginProgramSpreadsheetAddImageArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.addImage}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | The sheet the image was placed on |
+ * | `name` | `string` | The picture's (stable or generated) name |
+ */
+export const PluginProgramSpreadsheetAddImageResult = z.object({
+  sheetName: z.string(),
+  name: z.string(),
+})
+export type PluginProgramSpreadsheetAddImageResult = z.infer<
+  typeof PluginProgramSpreadsheetAddImageResult
+>