@snaptrude/plugin-core 0.8.0 → 0.9.0

package/src/api/presentation/shapes.ts

@@ -0,0 +1,274 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import {
+  PluginAnnotateFill,
+  PluginAnnotateGeoKind,
+  PluginAnnotateTextColor,
+  PluginAnnotateTextSize,
+} from "./annotate"
+
+/**
+ * Presentation shapes — a stable, plugin-owned shape lifecycle on Present-mode
+ * sheets.
+ *
+ * Where {@linkcode PluginPresentationAnnotateApi} is fire-and-forget (every call
+ * creates a new shape), this namespace keys each shape by a caller-chosen
+ * string, so rerunning an analysis **updates** its sheet output in place instead
+ * of duplicating it:
+ *
+ * - {@linkcode PluginPresentationShapesApi.upsert} — create or update the shape for a key
+ * - {@linkcode PluginPresentationShapesApi.remove} — delete the shape for a key
+ * - {@linkcode PluginPresentationShapesApi.removeAll} — delete every shape owned by the calling plugin
+ * - {@linkcode PluginPresentationShapesApi.list} — the calling plugin's shapes (key, shapeId, type)
+ *
+ * Shape ids are derived deterministically from the plugin id + key, so upserts
+ * converge across collaborators. Mutations require **Present mode to be open**
+ * (`list` is a never-throw read); each plugin sees and mutates only its own
+ * shapes.
+ *
+ * Accessed via `snaptrude.presentation.shapes`.
+ */
+export abstract class PluginPresentationShapesApi {
+  constructor() {}
+
+  /**
+   * Create or update the shape for a key.
+   *
+   * The `shape` spec is a discriminated union over the same four annotation
+   * kinds as `presentation.annotate` (`text`, `note`, `arrow`, `geo`), with the
+   * same option shapes. On first call for a key the shape is created on the
+   * target sheet (`options.sheetId`, default: the first sheet) and nested under
+   * the sheet frame; on later calls the existing shape is updated in place —
+   * same shape id, same sheet, one undo step. Positions/bounds are relative to
+   * the sheet's top-left, in canvas units. Requires Present mode to be open.
+   *
+   * @param key - Caller-chosen stable identifier for the shape (per plugin).
+   * @param shape - The desired shape ({@linkcode PluginPresentationShapeSpec}):
+   *   `{ type: "text" | "note" | "arrow" | "geo", ... }` with the matching
+   *   annotate options. Changing `type` for an existing key replaces the shape
+   *   (same shape id).
+   * @param options - Optional `sheetId` — the sheet to create the shape on
+   *   (defaults to the first sheet; ignored on update, the shape stays on its
+   *   sheet).
+   * @returns A {@linkcode PluginPresentationShapesUpsertResult} — the stable
+   *   `shapeId` and `created` (`true` on first upsert, `false` on update).
+   * @throws If Present mode is not open, the args are invalid, or the sheet id
+   *   is unknown.
+   *
+   * @examplePrompt Update the analysis label on the sheet instead of adding another one
+   * @examplePrompt Rerun the daylight report and refresh its annotations
+   * @examplePrompt Keep one "FAR: 2.4" text on Sheet 1 that updates on each run
+   * @examplePrompt Draw a highlight rectangle the plugin can move on the next run
+   *
+   * # Example
+   * ```ts
+   * const { shapeId, created } = await snaptrude.presentation.shapes.upsert("far-label", {
+   *   type: "text",
+   *   text: "FAR: 2.4",
+   *   position: { x: 40, y: 40 },
+   *   color: "blue",
+   * })
+   * ```
+   */
+  public abstract upsert(
+    key: string,
+    shape: PluginPresentationShapeSpec,
+    options?: { sheetId?: string },
+  ): PluginApiReturn<PluginPresentationShapesUpsertResult>
+
+  /**
+   * Delete the shape for a key.
+   *
+   * Removes the calling plugin's shape registered under `key`, if it exists.
+   * Requires Present mode to be open.
+   *
+   * @param key - The key passed to {@linkcode PluginPresentationShapesApi.upsert}.
+   * @returns `true` if a shape was deleted, `false` if no shape exists for the
+   *   key.
+   * @throws If Present mode is not open or the key is invalid.
+   *
+   * @examplePrompt Remove the FAR label from the sheet
+   * @examplePrompt Delete the highlight the plugin added earlier
+   * @examplePrompt Clear the "far-label" annotation
+   *
+   * # Example
+   * ```ts
+   * const removed = await snaptrude.presentation.shapes.remove("far-label")
+   * ```
+   */
+  public abstract remove(key: string): PluginApiReturn<boolean>
+
+  /**
+   * Delete every shape owned by the calling plugin.
+   *
+   * Removes all shapes the calling plugin has upserted (across all sheets) in
+   * one undo step. Requires Present mode to be open.
+   *
+   * @returns The number of shapes deleted.
+   * @throws If Present mode is not open.
+   *
+   * @examplePrompt Clear all annotations my plugin added
+   * @examplePrompt Reset the sheet output before rerunning the analysis
+   * @examplePrompt Remove every plugin-drawn shape
+   *
+   * # Example
+   * ```ts
+   * const deleted = await snaptrude.presentation.shapes.removeAll()
+   * ```
+   */
+  public abstract removeAll(): PluginApiReturn<number>
+
+  /**
+   * List the calling plugin's shapes.
+   *
+   * Returns one entry per live shape the calling plugin has upserted — its
+   * `key`, the underlying canvas `shapeId`, and the shape `type`. A never-throw
+   * read: returns an empty list when Present mode is closed.
+   *
+   * @returns A {@linkcode PluginPresentationShapesListResult} with the `shapes`
+   *   array (empty when Present mode is closed).
+   *
+   * @examplePrompt Which annotations has my plugin placed on the sheets?
+   * @examplePrompt List the plugin's shapes before refreshing them
+   * @examplePrompt Check whether the FAR label already exists
+   *
+   * # Example
+   * ```ts
+   * const { shapes } = await snaptrude.presentation.shapes.list()
+   * const hasLabel = shapes.some((s) => s.key === "far-label")
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginPresentationShapesListResult>
+}
+
+/**
+ * Desired shape for {@linkcode PluginPresentationShapesApi.upsert} — a
+ * discriminated union over the four annotate kinds, with the same option shapes
+ * as the matching `presentation.annotate` call:
+ *
+ * | `type` | Payload | Mirrors |
+ * |---|---|---|
+ * | `"text"` | `text`, `position?`, `size?`, `color?` | `annotate.text` |
+ * | `"note"` | `text`, `position?`, `color?`, `size?` | `annotate.note` |
+ * | `"arrow"` | `start`, `end`, `color?`, `size?` | `annotate.arrow` |
+ * | `"geo"` | `kind`, `bounds`, `color?`, `fill?` | `annotate.shape` |
+ *
+ * Positions/bounds are relative to the sheet's top-left, in canvas units.
+ */
+export const PluginPresentationShapeSpec = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("text"),
+    text: z.string(),
+    position: z.object({ x: z.number(), y: z.number() }).optional(),
+    size: PluginAnnotateTextSize.optional(),
+    color: PluginAnnotateTextColor.optional(),
+  }),
+  z.object({
+    type: z.literal("note"),
+    text: z.string(),
+    position: z.object({ x: z.number(), y: z.number() }).optional(),
+    color: PluginAnnotateTextColor.optional(),
+    size: PluginAnnotateTextSize.optional(),
+  }),
+  z.object({
+    type: z.literal("arrow"),
+    start: z.object({ x: z.number(), y: z.number() }),
+    end: z.object({ x: z.number(), y: z.number() }),
+    color: PluginAnnotateTextColor.optional(),
+    size: PluginAnnotateTextSize.optional(),
+  }),
+  z.object({
+    type: z.literal("geo"),
+    kind: PluginAnnotateGeoKind,
+    bounds: z.object({
+      x: z.number(),
+      y: z.number(),
+      w: z.number().positive(),
+      h: z.number().positive(),
+    }),
+    color: PluginAnnotateTextColor.optional(),
+    fill: PluginAnnotateFill.optional(),
+  }),
+])
+export type PluginPresentationShapeSpec = z.infer<
+  typeof PluginPresentationShapeSpec
+>
+
+/** The shape kind of a plugin-owned shape (the `type` discriminant of {@linkcode PluginPresentationShapeSpec}). */
+export const PluginPresentationShapeType = z.enum([
+  "text",
+  "note",
+  "arrow",
+  "geo",
+])
+export type PluginPresentationShapeType = z.infer<
+  typeof PluginPresentationShapeType
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationShapesApi.upsert}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `key` | `string` | Caller-chosen stable identifier (non-empty) |
+ * | `shape` | {@linkcode PluginPresentationShapeSpec} | The desired shape |
+ * | `sheetId` | `string \| undefined` | Sheet to create on (default: first sheet; ignored on update) |
+ */
+export const PluginPresentationShapesUpsertArgs = z.object({
+  key: z.string().min(1),
+  shape: PluginPresentationShapeSpec,
+  sheetId: z.string().optional(),
+})
+export type PluginPresentationShapesUpsertArgs = z.infer<
+  typeof PluginPresentationShapesUpsertArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationShapesApi.upsert}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | Stable id of the canvas shape for the key |
+ * | `created` | `boolean` | `true` if the shape was created, `false` if updated |
+ */
+export const PluginPresentationShapesUpsertResult = z.object({
+  shapeId: z.string(),
+  created: z.boolean(),
+})
+export type PluginPresentationShapesUpsertResult = z.infer<
+  typeof PluginPresentationShapesUpsertResult
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationShapesApi.remove}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `key` | `string` | The key the shape was upserted under (non-empty) |
+ */
+export const PluginPresentationShapesRemoveArgs = z.object({
+  key: z.string().min(1),
+})
+export type PluginPresentationShapesRemoveArgs = z.infer<
+  typeof PluginPresentationShapesRemoveArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationShapesApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapes` | `{ key: string; shapeId: string; type: `{@linkcode PluginPresentationShapeType}` }[]` | One entry per live plugin-owned shape |
+ */
+export const PluginPresentationShapesListResult = z.object({
+  shapes: z.array(
+    z.object({
+      key: z.string(),
+      shapeId: z.string(),
+      type: PluginPresentationShapeType,
+    }),
+  ),
+})
+export type PluginPresentationShapesListResult = z.infer<
+  typeof PluginPresentationShapesListResult
+>

package/src/api/program/site.ts

@@ -186,6 +186,56 @@ export abstract class PluginProgramSiteApi {
    * ```
    */
   public abstract getNorthAngle(): PluginApiReturn<PluginProgramSiteNorthAngleResult>
+
+  /**
+   * Get the IANA timezone of the project's geographic location.
+   *
+   * The timezone identifier (e.g. `"America/New_York"`, `"Asia/Kolkata"`)
+   * looked up from the same geo-location
+   * {@linkcode PluginProgramSiteApi.getLocation} returns. Returns `null` when
+   * the project is not geo-located on terrain.
+   *
+   * @returns A {@linkcode PluginProgramSiteTimezoneResult} — the IANA timezone
+   *   id string, or `null` when the project has no geo-located site.
+   *
+   * @examplePrompt What timezone is this project in?
+   * @examplePrompt Get the site's IANA timezone
+   * @examplePrompt What's the local time zone at the project location?
+   * @examplePrompt Which timezone should I use for the sun study schedule?
+   *
+   * # Example
+   * ```ts
+   * const timezone = await snaptrude.program.site.getTimezone()
+   * if (timezone) console.log(`Project timezone: ${timezone}`)
+   * ```
+   */
+  public abstract getTimezone(): PluginApiReturn<PluginProgramSiteTimezoneResult>
+
+  /**
+   * Get the weather file resolved for the project site.
+   *
+   * A lightweight read of the EPW weather file the `analysis.*` sun and
+   * daylight studies compute against — its catalog id, station name, content
+   * checksum, and how it was selected. This is the same file (same
+   * `weatherFileId`) that {@linkcode PluginAnalysisWeatherApi.getSeries} reads
+   * rows from and that a daylight run echoes in its provenance. Returns `null`
+   * when the project has no geo-located site (no weather file to resolve).
+   *
+   * @returns A {@linkcode PluginProgramSiteWeatherResult} —
+   *   `{ weatherFileId, station, checksum, selectionMethod }`, or `null` when
+   *   the project has no geo-located site.
+   *
+   * @examplePrompt Which weather file is my project using?
+   * @examplePrompt What EPW station was resolved for this site?
+   * @examplePrompt Get the weather file id for the daylight analysis
+   *
+   * # Example
+   * ```ts
+   * const weather = await snaptrude.program.site.getWeather()
+   * if (weather) console.log(weather.station, weather.selectionMethod)
+   * ```
+   */
+  public abstract getWeather(): PluginApiReturn<PluginProgramSiteWeatherResult>
 }
 
 /**
@@ -420,3 +470,48 @@ export const PluginProgramSiteNorthAngleResult = z.number().nullable()
 export type PluginProgramSiteNorthAngleResult = z.infer<
   typeof PluginProgramSiteNorthAngleResult
 >
+
+/**
+ * Result of {@linkcode PluginProgramSiteApi.getTimezone} — the IANA timezone
+ * id of the project's geo-location (e.g. `"Europe/London"`), or `null` when
+ * the project is not geo-located.
+ */
+export const PluginProgramSiteTimezoneResult = z.string().nullable()
+export type PluginProgramSiteTimezoneResult = z.infer<
+  typeof PluginProgramSiteTimezoneResult
+>
+
+/**
+ * A summary of the weather file resolved for the project site. Matches the
+ * relevant fields of `analysis.weather`'s `PluginWeatherSourceMeta`;
+ * `selectionMethod` is one of `"nearest-station"`, `"user-upload"`, or
+ * `"project-override"`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `weatherFileId` | `string` | Catalog id (same key as `core.io.import.epw`) |
+ * | `station` | `string` | Station/file name |
+ * | `checksum` | `string` | sha256 of the EPW file |
+ * | `selectionMethod` | `"nearest-station" \| "user-upload" \| "project-override"` | How the file was matched |
+ */
+export const PluginProgramSiteWeather = z.object({
+  weatherFileId: z.string(),
+  station: z.string(),
+  checksum: z.string(),
+  selectionMethod: z.enum([
+    "nearest-station",
+    "user-upload",
+    "project-override",
+  ]),
+})
+export type PluginProgramSiteWeather = z.infer<typeof PluginProgramSiteWeather>
+
+/**
+ * Result of {@linkcode PluginProgramSiteApi.getWeather} — the resolved weather
+ * file summary, or `null` when the project has no geo-located site.
+ */
+export const PluginProgramSiteWeatherResult =
+  PluginProgramSiteWeather.nullable()
+export type PluginProgramSiteWeatherResult = z.infer<
+  typeof PluginProgramSiteWeatherResult
+>

package/src/api/program/spreadsheet.ts

@@ -68,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).
    *
@@ -204,6 +210,9 @@ export abstract class PluginProgramSpreadsheetApi {
    * 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`
@@ -315,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).
    *
@@ -911,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(),
@@ -2011,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
 >
@@ -2169,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
+>