@snaptrude/plugin-core 0.7.1 → 0.8.0

package/src/api/program/layout.ts

@@ -19,10 +19,21 @@ import { PluginApiReturn } from "../../types"
  *    longer `"running"` — a run can take up to 20 minutes.
  * 3. {@linkcode PluginProgramLayoutApi.cancel} aborts an in-flight run.
  *
- * `arrange` produces several candidate layouts and **auto-commits the first
- * solution** as one undoable edit (there is no interactive solution-review
- * over the plugin boundary); `pack` re-shapes and applies its single result
- * directly. Both are **Pro-plan-gated**, matching the product UI.
+ * `arrange` produces several candidate layouts. By default it **auto-commits
+ * the first solution** as one undoable edit; pass `autoCommit: false` to hold
+ * the candidates for review instead — `getState` then reports
+ * `status: "pendingReview"` with `totalSolutions`, and
+ * {@linkcode PluginProgramLayoutApi.applySolution} commits the one you pick
+ * (the headless counterpart of the product's "Solution N of M → Apply" bar).
+ * `pack` re-shapes and applies its single result directly. Both are
+ * **Pro-plan-gated**, matching the product UI.
+ *
+ * {@linkcode PluginProgramLayoutApi.stack} is the **cross-storey** action —
+ * the product's *Pack in envelope* / auto-stack. It splits the building
+ * envelope by storey and packs each storey's departments into its slice as one
+ * undoable edit. Unlike `arrange` / `pack`, it is **not** the async-job model:
+ * it resolves inline when the whole multi-storey pack is done (no `getState`
+ * polling) and returns the storeys it had to skip. It is Pro-gated too.
  *
  * Accessed via `snaptrude.program.layout`.
  */
@@ -35,9 +46,16 @@ export abstract class PluginProgramLayoutApi {
    * Starts the backend job and **returns immediately** — poll
    * {@linkcode PluginProgramLayoutApi.getState} until `status` leaves
    * `"running"` (a run can take up to 20 minutes). The solver produces
-   * several candidate layouts; this **auto-commits the first solution** as one
-   * undoable edit (no interactive review over the plugin boundary). Starting a
-   * run while one is in flight replaces it.
+   * several candidate layouts; by default this **auto-commits the first
+   * solution** as one undoable edit. Pass `autoCommit: false` to review them
+   * instead: the run finishes with `status: "pendingReview"` and
+   * `totalSolutions` in `getState`, and
+   * {@linkcode PluginProgramLayoutApi.applySolution} commits the candidate you
+   * pick ({@linkcode PluginProgramLayoutApi.cancel} discards them). An
+   * arrange **without an envelope** applies directly (there is nothing to
+   * review) regardless of `autoCommit`. Starting a run while one is in flight
+   * replaces it; while solutions are pending review, new runs are refused —
+   * apply or cancel first.
    *
    * With no `options`, operates on the eligible Room/Department masses on the
    * active storey and auto-detects the single buildable envelope there.
@@ -53,11 +71,14 @@ export abstract class PluginProgramLayoutApi {
    * @throws When a `spaceId` / `departmentId` / `envelopeId` does not resolve.
    * @throws When more than one envelope is on the active storey and none was
    *   given (ambiguous).
+   * @throws When arrange solutions are pending review (apply or cancel them
+   *   first).
    * @throws When plugin writes are disabled.
    *
    * @examplePrompt Arrange the rooms in the envelope
    * @examplePrompt Lay out the departments inside the building envelope
    * @examplePrompt Auto-arrange the program spaces
+   * @examplePrompt Arrange the rooms but let me pick the solution
    *
    * # Example
    * ```ts
@@ -98,6 +119,8 @@ export abstract class PluginProgramLayoutApi {
    * @throws When a `spaceId` / `departmentId` / `envelopeId` does not resolve.
    * @throws When more than one envelope is on the active storey and none was
    *   given (ambiguous).
+   * @throws When arrange solutions are pending review (apply or cancel them
+   *   first).
    * @throws When plugin writes are disabled.
    *
    * @examplePrompt Pack the rooms into the envelope
@@ -118,6 +141,92 @@ export abstract class PluginProgramLayoutApi {
     options?: PluginProgramLayoutRunArgs,
   ): PluginApiReturn<PluginProgramLayoutRunResult>
 
+  /**
+   * Apply one of the pending arrange solutions.
+   *
+   * The headless counterpart of the product's **"Solution N of M → Apply"**
+   * review bar: after an {@linkcode PluginProgramLayoutApi.arrange} run
+   * started with `autoCommit: false` finishes with `status: "pendingReview"`,
+   * this commits the candidate at `index` (0-based,
+   * `0 ≤ index < totalSolutions` from
+   * {@linkcode PluginProgramLayoutApi.getState}) as **one undoable edit** and
+   * discards the other candidates. `getState` then reports
+   * `status: "active"`.
+   *
+   * @param index - 0-based index of the pending solution to apply.
+   * @returns A {@linkcode PluginProgramLayoutApplyResult} —
+   *   `{ success: true }` when the solution was applied.
+   * @throws When no arrange solutions are pending review (no
+   *   `arrange({ autoCommit: false })` run has finished, or its solutions were
+   *   already applied / cancelled).
+   * @throws When `index` is out of range for the pending solutions.
+   * @throws When plugin writes are disabled.
+   *
+   * @examplePrompt Apply the second arrange solution
+   * @examplePrompt Pick layout solution 3 and commit it
+   * @examplePrompt Apply the arrange solution I chose
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.layout.arrange({ autoCommit: false })
+   * let job = await snaptrude.program.layout.getState()
+   * while (job?.status === "running") {
+   *   await new Promise((r) => setTimeout(r, 5000))
+   *   job = await snaptrude.program.layout.getState()
+   * }
+   * if (job?.status === "pendingReview") {
+   *   console.log(`${job.totalSolutions} candidate layouts`)
+   *   await snaptrude.program.layout.applySolution(1) // commit the second one
+   * }
+   * ```
+   */
+  public abstract applySolution(
+    index: number,
+  ): PluginApiReturn<PluginProgramLayoutApplyResult>
+
+  /**
+   * Stack the program across **every storey** of the building — the product's
+   * *Pack in envelope* / auto-stack.
+   *
+   * Splits the building envelope massing into per-storey envelope slices, then
+   * packs each storey's departments into its slice, applying the whole
+   * multi-storey result as **one undoable edit**.
+   *
+   * Unlike {@linkcode PluginProgramLayoutApi.arrange} /
+   * {@linkcode PluginProgramLayoutApi.pack}, this **is not** the async-job
+   * model: `await` it and it resolves when the stack is done — there is no
+   * `getState` polling. It operates on the whole active model (no id / envelope
+   * arguments): it auto-discovers the departments and envelope on each storey.
+   *
+   * Storeys that have departments but **no envelope** are reported in
+   * `skippedStoreys` (nothing was packed there). A storey's departments must
+   * already be on that storey — `stack` does not move departments between
+   * floors, it lays out each floor's program into that floor's envelope.
+   *
+   * @returns A {@linkcode PluginProgramLayoutStackResult} — `success: true`
+   *   with the (possibly empty) `skippedStoreys` when the stack was applied, or
+   *   `success: false` with an `error` when the run failed (e.g. the adjacency
+   *   service was unreachable).
+   * @throws When the project is not on a Pro plan.
+   * @throws When plugin writes are disabled.
+   * @throws When an `arrange` / `pack` run, or another `stack`, is already in
+   *   flight, or arrange solutions are pending review (finish, apply, or
+   *   `cancel` first).
+   *
+   * @examplePrompt Stack the program across all floors
+   * @examplePrompt Auto-stack the departments into the envelope on every storey
+   * @examplePrompt Pack the whole building's program into its envelope
+   *
+   * # Example
+   * ```ts
+   * const { success, skippedStoreys, error } = await snaptrude.program.layout.stack()
+   * if (!success) throw new Error(error)
+   * if (skippedStoreys.length)
+   *   console.warn(`No envelope on storeys: ${skippedStoreys.join(", ")}`)
+   * ```
+   */
+  public abstract stack(): PluginApiReturn<PluginProgramLayoutStackResult>
+
   /**
    * Get the state of the layout run.
    *
@@ -130,6 +239,10 @@ export abstract class PluginProgramLayoutApi {
    * | `"running"` | A run is in flight — keep polling |
    * | `"active"` | The run finished and its layout is applied to the model |
    * | `"inactive"` | A run finished without applying a layout (the solver failed or found no solution) |
+   * | `"pendingReview"` | An `arrange({ autoCommit: false })` run finished and its candidates await {@linkcode PluginProgramLayoutApi.applySolution} / {@linkcode PluginProgramLayoutApi.cancel} |
+   *
+   * While `status` is `"pendingReview"` the state also carries
+   * `totalSolutions` — the number of candidate layouts to pick from.
    *
    * @returns A {@linkcode PluginProgramLayoutStateResult} with the run
    *   `status`, or `null` when no run result is available (never ran or was
@@ -150,11 +263,13 @@ export abstract class PluginProgramLayoutApi {
   /**
    * Cancel the in-flight layout run.
    *
-   * Aborts the backend job and discards any pending solution. A no-op
-   * (returns `false`) when nothing is running.
+   * Aborts the backend job and discards any pending solution. Also discards
+   * a finished run's **pending-review** solutions (after
+   * `arrange({ autoCommit: false })`) without applying one. A no-op (returns
+   * `false`) when nothing is running and nothing is pending.
    *
-   * @returns `true` when a run was cancelled, `false` when nothing was
-   *   running.
+   * @returns `true` when a run was cancelled or pending solutions were
+   *   discarded, `false` when there was nothing to cancel.
    * @throws When plugin writes are disabled.
    *
    * @examplePrompt Cancel the arrange
@@ -180,11 +295,13 @@ export abstract class PluginProgramLayoutApi {
  * | `spaceIds` | `string[] \| undefined` | Component ids of the Room masses to lay out |
  * | `departmentIds` | `string[] \| undefined` | Component ids of the Department masses to lay out |
  * | `envelopeId` | `string \| undefined` | The envelope to fit into — a mass component id or a buildable-envelope handle (`be_…`); omit to auto-detect the single envelope on the active storey |
+ * | `autoCommit` | `boolean \| undefined` | `arrange` only — `true` / omitted (default) auto-commits the first candidate solution; `false` holds the candidates for review via {@linkcode PluginProgramLayoutApi.applySolution}. Ignored by `pack` (it applies its single result directly) |
  */
 export const PluginProgramLayoutRunArgs = z.object({
   spaceIds: z.array(z.string()).optional(),
   departmentIds: z.array(z.string()).optional(),
   envelopeId: z.string().optional(),
+  autoCommit: z.boolean().optional(),
 })
 export type PluginProgramLayoutRunArgs = z.infer<
   typeof PluginProgramLayoutRunArgs
@@ -217,11 +334,13 @@ export type PluginProgramLayoutRunResult = z.infer<
  * | `"running"` | A run is in flight — keep polling |
  * | `"active"` | The run finished and its layout is applied to the model |
  * | `"inactive"` | A run finished without applying a layout (the solver failed or found no solution) |
+ * | `"pendingReview"` | An `arrange({ autoCommit: false })` run finished and its candidate solutions await {@linkcode PluginProgramLayoutApi.applySolution} / {@linkcode PluginProgramLayoutApi.cancel} |
  */
 export const PluginProgramLayoutJobStatus = z.enum([
   "running",
   "active",
   "inactive",
+  "pendingReview",
 ])
 export type PluginProgramLayoutJobStatus = z.infer<
   typeof PluginProgramLayoutJobStatus
@@ -232,10 +351,12 @@ export type PluginProgramLayoutJobStatus = z.infer<
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `status` | {@linkcode PluginProgramLayoutJobStatus} | `"running"` \| `"active"` \| `"inactive"` |
+ * | `status` | {@linkcode PluginProgramLayoutJobStatus} | `"running"` \| `"active"` \| `"inactive"` \| `"pendingReview"` |
+ * | `totalSolutions` | `number \| undefined` | Number of candidate solutions awaiting review — present only while `status` is `"pendingReview"` |
  */
 export const PluginProgramLayoutJobState = z.object({
   status: PluginProgramLayoutJobStatus,
+  totalSolutions: z.number().int().optional(),
 })
 export type PluginProgramLayoutJobState = z.infer<
   typeof PluginProgramLayoutJobState
@@ -250,3 +371,52 @@ export const PluginProgramLayoutStateResult =
 export type PluginProgramLayoutStateResult = z.infer<
   typeof PluginProgramLayoutStateResult
 >
+
+/**
+ * Arguments for {@linkcode PluginProgramLayoutApi.applySolution}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `index` | `number` | 0-based index of the pending solution to apply (`0 ≤ index < totalSolutions`) |
+ */
+export const PluginProgramLayoutApplySolutionArgs = z.object({
+  index: z.number().int().min(0),
+})
+export type PluginProgramLayoutApplySolutionArgs = z.infer<
+  typeof PluginProgramLayoutApplySolutionArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramLayoutApi.applySolution}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `success` | `boolean` | Whether the chosen solution was applied |
+ * | `error` | `string \| undefined` | Failure reason when `success` is `false` |
+ */
+export const PluginProgramLayoutApplyResult = z.object({
+  success: z.boolean(),
+  error: z.string().optional(),
+})
+export type PluginProgramLayoutApplyResult = z.infer<
+  typeof PluginProgramLayoutApplyResult
+>
+
+/**
+ * Result of {@linkcode PluginProgramLayoutApi.stack} — reports whether the
+ * cross-storey stack was applied and which storeys were skipped.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `success` | `boolean` | Whether the stack was applied |
+ * | `skippedStoreys` | `number[]` | Storey values that had departments but no envelope, so nothing was packed there |
+ * | `error` | `string \| undefined` | Failure reason when `success` is `false` |
+ */
+export const PluginProgramLayoutStackResult = z.object({
+  success: z.boolean(),
+  skippedStoreys: z.array(z.number()),
+  error: z.string().optional(),
+})
+export type PluginProgramLayoutStackResult = z.infer<
+  typeof PluginProgramLayoutStackResult
+>

package/src/api/program/site.ts

@@ -6,8 +6,9 @@ import { PluginAreaUnit } from "./metrics"
  * Program site — read the planning context of the project's site/plot.
  *
  * The **site** is the set of plot/parcel footprints the program is planned
- * against: their total area, per-parcel footprints (in scene XZ coordinates),
- * and — when the project is geo-located on terrain — their geographic
+ * against: their total area, per-parcel footprints (world XZ plan coordinates
+ * in Snaptrude units — the same plan space as a space's `planPoints`), and —
+ * when the project is geo-located on terrain — their geographic
  * (latitude/longitude) rings. This is the program-planning view of the site;
  * zoning numbers (setbacks, FAR/FSI, height limits) live in the site-analysis
  * sheet and are not read here.
@@ -64,7 +65,8 @@ export abstract class PluginProgramSiteApi {
   public abstract getArea(): PluginApiReturn<PluginProgramSiteAreaResult>
 
   /**
-   * List the site parcels with their footprints (in scene coordinates).
+   * List the site parcels with their footprints (world XZ plan coordinates,
+   * Snaptrude units).
    *
    * @returns A {@linkcode PluginProgramSiteListPolygonsResult} with each parcel's
    *   id, area, label, and 2D footprint (XZ ground-plane points). Empty when the
@@ -88,7 +90,7 @@ export abstract class PluginProgramSiteApi {
    *
    * Only available when the project is geo-located on terrain; returns `[]` (no
    * rings) otherwise. Use {@linkcode PluginProgramSiteApi.listPolygons} for the
-   * scene-coordinate footprints that are always available.
+   * world-coordinate footprints that are always available.
    *
    * @returns A {@linkcode PluginProgramSiteListGeoPolygonsResult} with one ring
    *   of `{ lat, lng, alt }` points per parcel.
@@ -187,13 +189,14 @@ export abstract class PluginProgramSiteApi {
 }
 
 /**
- * A 2D ground-plane point of a site parcel footprint, in scene coordinates
- * (metres on the project's XZ plane).
+ * A 2D ground-plane point of a site parcel footprint, in world XZ plan
+ * coordinates (Snaptrude units) — the same plan space as a space's
+ * `planPoints`, so site parcels overlay space footprints directly.
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `x` | `number` | X coordinate (scene metres) |
- * | `z` | `number` | Z coordinate (scene metres) |
+ * | `x` | `number` | X coordinate (world, Snaptrude units) |
+ * | `z` | `number` | Z coordinate (world, Snaptrude units) |
  */
 export const PluginSiteFootprintPoint = z.object({
   x: z.number(),

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
@@ -128,13 +129,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 +152,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 +164,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 +187,27 @@ 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.
+   *
+   * @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 +216,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>
 
   /**
@@ -378,6 +396,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 +647,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 +739,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 +889,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.
@@ -977,7 +1027,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 +1049,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 +1338,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. */