@snaptrude/plugin-core 0.9.17 → 0.9.18-networks-20261016.1

package/src/api/program/areas.ts

@@ -1,408 +1,408 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../types"
-import { PluginAreaUnit } from "./metrics"
-import { PluginAreaClass } from "../entity/space"
-import { ComponentHandle } from "../../handles"
-
-/**
- * Program areas — the FAR / built-up-area rollup for the active program.
- *
- * This is the zoning-compliance lens on the model: carpet / built-up / excluded
- * area totals, the site area, and the achieved-vs-target **FAR** (Floor Area
- * Ratio). It complements {@linkcode PluginProgramMetricsApi}, which is the
- * department-allocation lens (targets vs allocated area per department); this
- * namespace is the whole-program area/FAR summary and its groupings.
- *
- * **Net vs gross:** the `carpet` / `builtUp` / `excluded` figures are the three
- * area *classes* — every space's whole footprint lands in exactly one, chosen
- * by its `areaClass` (see {@linkcode PluginProgramAreaMember.areaClass}). In UI
- * terms `carpet` is the **Net Internal Area** (Σ of `NET`-classed spaces), and
- * `builtUp` is the **Gross External Area** (Σ of `GROSS`-classed spaces) — so
- * "net" and "gross" are the plain-English synonyms for `carpet` and `builtUp`.
- * These are not wall-thickness carpet-vs-super-built-up; there is no common-area
- * math. Note the summary also folds in non-mass elements (floors count as NET,
- * slabs as GROSS), so **summing `listMembers` spaces does not reconcile to the
- * summary totals**.
- *
- * `achievedFar` is **derived and read-only** — computed from built-up area and
- * site area. `targetFar` is the goal you set (via {@linkcode
- * PluginProgramAreasApi.update}); the two are the same ratio, one measured and
- * one intended. The surface speaks **FAR only** — there is no FSI alias.
- *
- * Reads return plain records and never throw. Because the engine only recomputes
- * the breakdown live while the Area sidebar is open, a headless plugin should call
- * {@linkcode PluginProgramAreasApi.refresh} first to guarantee the reads are fresh.
- * The only write — {@linkcode PluginProgramAreasApi.update} — is a non-undoable
- * settings write for the FAR inputs. With an active design option (proposal),
- * those inputs are per-option: `update` writes and the reads report the active
- * option's own target FAR / site area / deviation, matching the product's Area
- * settings dialog.
- *
- * Accessed via `snaptrude.program.areas`.
- */
-export abstract class PluginProgramAreasApi {
-  constructor() {}
-
-  /**
-   * Get the program area summary.
-   *
-   * Returns the whole-program totals — carpet / built-up / excluded area, site
-   * area, and achieved vs target FAR — with the area unit they are reported in.
-   *
-   * @returns A {@linkcode PluginProgramAreaSummary}. `achievedFar` is `null` when
-   *   the site area or target FAR is not set.
-   *
-   * @examplePrompt What's my FAR right now?
-   * @examplePrompt Give me the program area summary
-   * @examplePrompt What is my net internal area vs gross external area?
-   * @examplePrompt How much net and gross area do I have?
-   * @examplePrompt How much built-up area have I used against the site area?
-   * @examplePrompt Am I within my FAR target?
-   *
-   * # Example
-   * ```ts
-   * const s = await snaptrude.program.areas.get()
-   * console.log(s.builtUp, s.siteArea, s.achievedFar, s.targetFar, s.areaUnit)
-   * ```
-   */
-  public abstract get(): PluginApiReturn<PluginProgramAreasGetResult>
-
-  /**
-   * List the program area rollup grouped by a facet.
-   *
-   * Breaks the program's area totals into buckets — by label, storey, building,
-   * department, or tag category.
-   *
-   * @param groupBy - The facet to group by (a {@linkcode PluginProgramAreaGroupBy}).
-   * @param categoryId - The tag category to group by (required when `groupBy` is
-   *   `"tagCategories"`).
-   * @returns A {@linkcode PluginProgramAreasListResult} with a `groups` array
-   *   (empty when the program has no spaces).
-   *
-   * @examplePrompt Break down the area by storey
-   * @examplePrompt Break down net vs gross area by storey
-   * @examplePrompt Show the area rollup per department
-   * @examplePrompt Group the built-up area by building
-   *
-   * # Example
-   * ```ts
-   * const { groups } = await snaptrude.program.areas.list("storeys")
-   * for (const g of groups) console.log(g.name, g.builtUp, g.count)
-   * ```
-   */
-  public abstract list(
-    groupBy: PluginProgramAreaGroupBy,
-    categoryId?: string,
-  ): PluginApiReturn<PluginProgramAreasListResult>
-
-  /**
-   * List the spaces that make up one area group.
-   *
-   * Drills into a single bucket returned by {@linkcode
-   * PluginProgramAreasApi.list} and returns its member spaces with their per-space
-   * area figures.
-   *
-   * @param groupBy - The same facet used to produce the group (a {@linkcode
-   *   PluginProgramAreaGroupBy}).
-   * @param groupId - The id of the group to expand.
-   * @param categoryId - The tag category context (required when `groupBy` is
-   *   `"tagCategories"`).
-   * @returns A {@linkcode PluginProgramAreasListMembersResult} with a `members`
-   *   array (empty when the group is missing or empty).
-   *
-   * @examplePrompt List the spaces on this storey with their areas
-   * @examplePrompt Which spaces are net and which are gross on this storey?
-   * @examplePrompt What rooms are in the Bedrooms department bucket?
-   * @examplePrompt Break the storey area down into individual spaces
-   *
-   * # Example
-   * ```ts
-   * const { members } = await snaptrude.program.areas.listMembers("storeys", "st_2")
-   * for (const m of members) console.log(m.label, m.carpet)
-   * ```
-   */
-  public abstract listMembers(
-    groupBy: PluginProgramAreaGroupBy,
-    groupId: string,
-    categoryId?: string,
-  ): PluginApiReturn<PluginProgramAreasListMembersResult>
-
-  /**
-   * Update the program's FAR settings.
-   *
-   * A **sparse** update of the program-level FAR inputs — target FAR, the site
-   * area, and the allowed deviation. This is a **non-undoable settings write**
-   * (persisted with the project). `achievedFar` recomputes from these.
-   *
-   * **Design options:** when a design option (proposal) is active, the FAR
-   * inputs are **scoped to that design option** — exactly like the product's
-   * Area settings dialog. `update` writes the active option's settings (each
-   * option keeps its own target FAR / site area / deviation) and the reads
-   * ({@linkcode PluginProgramAreasApi.get} etc.) report that same scope.
-   * Without design options there is a single project-wide set of FAR inputs.
-   *
-   * @param options - Any of `targetFar`, `siteArea`, `deviation`; omitted fields
-   *   are left unchanged.
-   * @returns The recomputed {@linkcode PluginProgramAreaSummary}.
-   * @throws If a value is out of range.
-   *
-   * @examplePrompt Set the target FAR to 2.5
-   * @examplePrompt Override the site area to 5000
-   * @examplePrompt Allow a 10 percent FAR deviation
-   *
-   * # Example
-   * ```ts
-   * const s = await snaptrude.program.areas.update({ targetFar: 2.5 })
-   * console.log(s.achievedFar, s.targetFar)
-   * ```
-   */
-  public abstract update(options?: {
-    targetFar?: number
-    siteArea?: number
-    deviation?: number
-  }): PluginApiReturn<PluginProgramAreasUpdateResult>
-
-  /**
-   * Force the area breakdown to recompute, then return the fresh summary.
-   *
-   * The engine recomputes the carpet / built-up / FAR totals live **only while the
-   * Area sidebar is open**. A plugin running with the sidebar closed can therefore
-   * read a stale — or never-computed — snapshot from {@linkcode
-   * PluginProgramAreasApi.get} / {@linkcode PluginProgramAreasApi.list}. Call
-   * `refresh` first to guarantee those reads reflect the current model. It is a
-   * read (no write gate) — it recomputes derived totals, it does not change the model.
-   *
-   * **Cost:** a full pass over every space, floor and mass in the active structure.
-   * Not free on large models — call it once before a batch of reads, not per read.
-   *
-   * @returns The freshly-recomputed {@linkcode PluginProgramAreaSummary}.
-   *
-   * @examplePrompt Recompute the area totals before I read them
-   * @examplePrompt Refresh the FAR numbers
-   * @examplePrompt Make sure the area breakdown is up to date
-   *
-   * # Example
-   * ```ts
-   * const s = await snaptrude.program.areas.refresh()
-   * const { groups } = await snaptrude.program.areas.list("storeys") // now fresh
-   * console.log(s.builtUp, groups.length)
-   * ```
-   */
-  public abstract refresh(): PluginApiReturn<PluginProgramAreasRefreshResult>
-}
-
-/**
- * The whole-program area / FAR summary. All area figures are in `areaUnit`;
- * ratios (`achievedFar`, `targetFar`, `deviation`) are unitless.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `count` | `number` | Number of spaces in the program (a count, not an area) |
- * | `hiddenCount` | `number` | Number of those spaces that are currently hidden |
- * | `carpet` | `number` | Total **Net Internal Area** ("net") — Σ `NET`-classed spaces + floors — in `areaUnit` |
- * | `builtUp` | `number` | Total **Gross External Area** ("gross") — Σ `GROSS`-classed spaces + slabs — in `areaUnit` |
- * | `excluded` | `number` | Total **Excluded Area** — Σ `EXCLUDED`-classed spaces — in `areaUnit` |
- * | `farBuiltUp` | `number` | Built-up area that counts toward FAR, in `areaUnit` |
- * | `siteArea` | `number` | Site/plot area in `areaUnit` |
- * | `achievedFar` | `number \| null` | Derived FAR (`farBuiltUp / siteArea`); `null` when site area or target FAR is unset |
- * | `targetFar` | `number` | The target FAR goal (set via `update`) |
- * | `deviation` | `number` | Allowed FAR deviation, as a percentage |
- * | `areaUnit` | `"ft2" \| "m2"` | The unit every area figure above is reported in |
- */
-export const PluginProgramAreaSummary = z.object({
-  count: z.number().int(),
-  hiddenCount: z.number().int(),
-  carpet: z.number(),
-  builtUp: z.number(),
-  excluded: z.number(),
-  farBuiltUp: z.number(),
-  siteArea: z.number(),
-  achievedFar: z.number().nullable(),
-  targetFar: z.number(),
-  deviation: z.number(),
-  areaUnit: PluginAreaUnit,
-})
-export type PluginProgramAreaSummary = z.infer<typeof PluginProgramAreaSummary>
-
-/**
- * One bucket of the area rollup. Carpet / built-up / excluded figures are in the
- * program's area unit (see {@linkcode PluginProgramAreaSummary.areaUnit});
- * `targetArea` is in `targetUnit`.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `groupId` | `string` | Stable id of the group (e.g. storey id, department id) |
- * | `name` | `string` | Display name of the group |
- * | `color` | `string` | CSS hex color string for the group |
- * | `carpet` | `number` | Net Internal Area ("net") for this group |
- * | `builtUp` | `number` | Gross External Area ("gross") for this group |
- * | `excluded` | `number` | Excluded area for this group |
- * | `count` | `number` | Number of spaces in this group |
- * | `targetArea` | `number` | Target area for this group, in `targetUnit` |
- * | `targetUnit` | `"ft2" \| "m2"` | The unit `targetArea` is reported in |
- */
-export const PluginProgramAreaGroup = z.object({
-  groupId: z.string(),
-  name: z.string(),
-  color: z.string(),
-  carpet: z.number(),
-  builtUp: z.number(),
-  excluded: z.number(),
-  count: z.number().int(),
-  targetArea: z.number(),
-  targetUnit: PluginAreaUnit,
-})
-export type PluginProgramAreaGroup = z.infer<typeof PluginProgramAreaGroup>
-
-/**
- * A single space within an area group. Area figures are in the program's area
- * unit (see {@linkcode PluginProgramAreaSummary.areaUnit}).
- *
- * `areaClass` is the space's effective classification — it decides which of the
- * three buckets the space's whole footprint lands in: `NET` → `carpet` ("net"),
- * `GROSS` → `builtUp` ("gross"), `EXCLUDED` → `excluded`. So for any one member
- * exactly one of `carpet` / `builtUp` / `excluded` is non-zero.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `ComponentHandle` | `Component.id` of the space (never a mesh handle) |
- * | `label` | `string` | Display label of the space |
- * | `areaClass` | {@linkcode PluginAreaClass} | Effective area class — `"NET"` (→ `carpet`), `"GROSS"` (→ `builtUp`), or `"EXCLUDED"` |
- * | `carpet` | `number` | Net area of the space (non-zero when `areaClass` is `"NET"`) |
- * | `builtUp` | `number` | Gross area of the space (non-zero when `areaClass` is `"GROSS"`) |
- * | `excluded` | `number` | Excluded area of the space (non-zero when `areaClass` is `"EXCLUDED"`) |
- * | `isVisible` | `boolean` | Whether the space is currently visible |
- */
-export const PluginProgramAreaMember = z.object({
-  id: ComponentHandle,
-  label: z.string(),
-  areaClass: PluginAreaClass,
-  carpet: z.number(),
-  builtUp: z.number(),
-  excluded: z.number(),
-  isVisible: z.boolean(),
-})
-export type PluginProgramAreaMember = z.infer<typeof PluginProgramAreaMember>
-
-/** The facet to group the area rollup by. */
-export const PluginProgramAreaGroupBy = z.enum([
-  "labels",
-  "storeys",
-  "buildings",
-  "departments",
-  "tagCategories",
-])
-export type PluginProgramAreaGroupBy = z.infer<typeof PluginProgramAreaGroupBy>
-
-/** Result of {@linkcode PluginProgramAreasApi.get} — the program area summary. */
-export const PluginProgramAreasGetResult = PluginProgramAreaSummary
-export type PluginProgramAreasGetResult = z.infer<
-  typeof PluginProgramAreasGetResult
->
-
-/**
- * Arguments for {@linkcode PluginProgramAreasApi.list}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `groupBy` | {@linkcode PluginProgramAreaGroupBy} | The facet to group by |
- * | `categoryId` | `string \| undefined` | Tag category to group by; required when `groupBy` is `"tagCategories"` |
- */
-export const PluginProgramAreasListArgs = z
-  .object({
-    groupBy: PluginProgramAreaGroupBy,
-    categoryId: z.string().optional(),
-  })
-  .refine((v) => v.groupBy !== "tagCategories" || v.categoryId != null, {
-    message: 'categoryId is required when groupBy is "tagCategories"',
-  })
-export type PluginProgramAreasListArgs = z.infer<
-  typeof PluginProgramAreasListArgs
->
-
-/**
- * Result of {@linkcode PluginProgramAreasApi.list}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `groups` | {@linkcode PluginProgramAreaGroup}`[]` | The area buckets (empty when the program has no spaces) |
- */
-export const PluginProgramAreasListResult = z.object({
-  groups: z.array(PluginProgramAreaGroup),
-})
-export type PluginProgramAreasListResult = z.infer<
-  typeof PluginProgramAreasListResult
->
-
-/**
- * Arguments for {@linkcode PluginProgramAreasApi.listMembers}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `groupBy` | {@linkcode PluginProgramAreaGroupBy} | The facet the group came from |
- * | `groupId` | `string` | The id of the group to expand |
- * | `categoryId` | `string \| undefined` | Tag category context; required when `groupBy` is `"tagCategories"` |
- */
-export const PluginProgramAreasListMembersArgs = z
-  .object({
-    groupBy: PluginProgramAreaGroupBy,
-    groupId: z.string(),
-    categoryId: z.string().optional(),
-  })
-  .refine((v) => v.groupBy !== "tagCategories" || v.categoryId != null, {
-    message: 'categoryId is required when groupBy is "tagCategories"',
-  })
-export type PluginProgramAreasListMembersArgs = z.infer<
-  typeof PluginProgramAreasListMembersArgs
->
-
-/**
- * Result of {@linkcode PluginProgramAreasApi.listMembers}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `members` | {@linkcode PluginProgramAreaMember}`[]` | The group's member spaces (empty when missing or empty) |
- */
-export const PluginProgramAreasListMembersResult = z.object({
-  members: z.array(PluginProgramAreaMember),
-})
-export type PluginProgramAreasListMembersResult = z.infer<
-  typeof PluginProgramAreasListMembersResult
->
-
-/**
- * Arguments for {@linkcode PluginProgramAreasApi.update}. Sparse — only the
- * provided fields are changed.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `targetFar` | `number \| undefined` | New target FAR (≥ 0) |
- * | `siteArea` | `number \| undefined` | Site-area override (> 0), in the program's area unit |
- * | `deviation` | `number \| undefined` | Allowed FAR deviation percentage (0–100) |
- */
-export const PluginProgramAreasUpdateArgs = z.object({
-  targetFar: z.number().min(0).optional(),
-  siteArea: z.number().positive().optional(),
-  deviation: z.number().min(0).max(100).optional(),
-})
-export type PluginProgramAreasUpdateArgs = z.infer<
-  typeof PluginProgramAreasUpdateArgs
->
-
-/**
- * Result of {@linkcode PluginProgramAreasApi.update} — the recomputed program
- * area summary.
- */
-export const PluginProgramAreasUpdateResult = PluginProgramAreaSummary
-export type PluginProgramAreasUpdateResult = z.infer<
-  typeof PluginProgramAreasUpdateResult
->
-
-/**
- * Result of {@linkcode PluginProgramAreasApi.refresh} — the freshly-recomputed
- * program area summary.
- */
-export const PluginProgramAreasRefreshResult = PluginProgramAreaSummary
-export type PluginProgramAreasRefreshResult = z.infer<
-  typeof PluginProgramAreasRefreshResult
->
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { PluginAreaUnit } from "./metrics"
+import { PluginAreaClass } from "../entity/space"
+import { ComponentHandle } from "../../handles"
+
+/**
+ * Program areas — the FAR / built-up-area rollup for the active program.
+ *
+ * This is the zoning-compliance lens on the model: carpet / built-up / excluded
+ * area totals, the site area, and the achieved-vs-target **FAR** (Floor Area
+ * Ratio). It complements {@linkcode PluginProgramMetricsApi}, which is the
+ * department-allocation lens (targets vs allocated area per department); this
+ * namespace is the whole-program area/FAR summary and its groupings.
+ *
+ * **Net vs gross:** the `carpet` / `builtUp` / `excluded` figures are the three
+ * area *classes* — every space's whole footprint lands in exactly one, chosen
+ * by its `areaClass` (see {@linkcode PluginProgramAreaMember.areaClass}). In UI
+ * terms `carpet` is the **Net Internal Area** (Σ of `NET`-classed spaces), and
+ * `builtUp` is the **Gross External Area** (Σ of `GROSS`-classed spaces) — so
+ * "net" and "gross" are the plain-English synonyms for `carpet` and `builtUp`.
+ * These are not wall-thickness carpet-vs-super-built-up; there is no common-area
+ * math. Note the summary also folds in non-mass elements (floors count as NET,
+ * slabs as GROSS), so **summing `listMembers` spaces does not reconcile to the
+ * summary totals**.
+ *
+ * `achievedFar` is **derived and read-only** — computed from built-up area and
+ * site area. `targetFar` is the goal you set (via {@linkcode
+ * PluginProgramAreasApi.update}); the two are the same ratio, one measured and
+ * one intended. The surface speaks **FAR only** — there is no FSI alias.
+ *
+ * Reads return plain records and never throw. Because the engine only recomputes
+ * the breakdown live while the Area sidebar is open, a headless plugin should call
+ * {@linkcode PluginProgramAreasApi.refresh} first to guarantee the reads are fresh.
+ * The only write — {@linkcode PluginProgramAreasApi.update} — is a non-undoable
+ * settings write for the FAR inputs. With an active design option (proposal),
+ * those inputs are per-option: `update` writes and the reads report the active
+ * option's own target FAR / site area / deviation, matching the product's Area
+ * settings dialog.
+ *
+ * Accessed via `snaptrude.program.areas`.
+ */
+export abstract class PluginProgramAreasApi {
+  constructor() {}
+
+  /**
+   * Get the program area summary.
+   *
+   * Returns the whole-program totals — carpet / built-up / excluded area, site
+   * area, and achieved vs target FAR — with the area unit they are reported in.
+   *
+   * @returns A {@linkcode PluginProgramAreaSummary}. `achievedFar` is `null` when
+   *   the site area or target FAR is not set.
+   *
+   * @examplePrompt What's my FAR right now?
+   * @examplePrompt Give me the program area summary
+   * @examplePrompt What is my net internal area vs gross external area?
+   * @examplePrompt How much net and gross area do I have?
+   * @examplePrompt How much built-up area have I used against the site area?
+   * @examplePrompt Am I within my FAR target?
+   *
+   * # Example
+   * ```ts
+   * const s = await snaptrude.program.areas.get()
+   * console.log(s.builtUp, s.siteArea, s.achievedFar, s.targetFar, s.areaUnit)
+   * ```
+   */
+  public abstract get(): PluginApiReturn<PluginProgramAreasGetResult>
+
+  /**
+   * List the program area rollup grouped by a facet.
+   *
+   * Breaks the program's area totals into buckets — by label, storey, building,
+   * department, or tag category.
+   *
+   * @param groupBy - The facet to group by (a {@linkcode PluginProgramAreaGroupBy}).
+   * @param categoryId - The tag category to group by (required when `groupBy` is
+   *   `"tagCategories"`).
+   * @returns A {@linkcode PluginProgramAreasListResult} with a `groups` array
+   *   (empty when the program has no spaces).
+   *
+   * @examplePrompt Break down the area by storey
+   * @examplePrompt Break down net vs gross area by storey
+   * @examplePrompt Show the area rollup per department
+   * @examplePrompt Group the built-up area by building
+   *
+   * # Example
+   * ```ts
+   * const { groups } = await snaptrude.program.areas.list("storeys")
+   * for (const g of groups) console.log(g.name, g.builtUp, g.count)
+   * ```
+   */
+  public abstract list(
+    groupBy: PluginProgramAreaGroupBy,
+    categoryId?: string,
+  ): PluginApiReturn<PluginProgramAreasListResult>
+
+  /**
+   * List the spaces that make up one area group.
+   *
+   * Drills into a single bucket returned by {@linkcode
+   * PluginProgramAreasApi.list} and returns its member spaces with their per-space
+   * area figures.
+   *
+   * @param groupBy - The same facet used to produce the group (a {@linkcode
+   *   PluginProgramAreaGroupBy}).
+   * @param groupId - The id of the group to expand.
+   * @param categoryId - The tag category context (required when `groupBy` is
+   *   `"tagCategories"`).
+   * @returns A {@linkcode PluginProgramAreasListMembersResult} with a `members`
+   *   array (empty when the group is missing or empty).
+   *
+   * @examplePrompt List the spaces on this storey with their areas
+   * @examplePrompt Which spaces are net and which are gross on this storey?
+   * @examplePrompt What rooms are in the Bedrooms department bucket?
+   * @examplePrompt Break the storey area down into individual spaces
+   *
+   * # Example
+   * ```ts
+   * const { members } = await snaptrude.program.areas.listMembers("storeys", "st_2")
+   * for (const m of members) console.log(m.label, m.carpet)
+   * ```
+   */
+  public abstract listMembers(
+    groupBy: PluginProgramAreaGroupBy,
+    groupId: string,
+    categoryId?: string,
+  ): PluginApiReturn<PluginProgramAreasListMembersResult>
+
+  /**
+   * Update the program's FAR settings.
+   *
+   * A **sparse** update of the program-level FAR inputs — target FAR, the site
+   * area, and the allowed deviation. This is a **non-undoable settings write**
+   * (persisted with the project). `achievedFar` recomputes from these.
+   *
+   * **Design options:** when a design option (proposal) is active, the FAR
+   * inputs are **scoped to that design option** — exactly like the product's
+   * Area settings dialog. `update` writes the active option's settings (each
+   * option keeps its own target FAR / site area / deviation) and the reads
+   * ({@linkcode PluginProgramAreasApi.get} etc.) report that same scope.
+   * Without design options there is a single project-wide set of FAR inputs.
+   *
+   * @param options - Any of `targetFar`, `siteArea`, `deviation`; omitted fields
+   *   are left unchanged.
+   * @returns The recomputed {@linkcode PluginProgramAreaSummary}.
+   * @throws If a value is out of range.
+   *
+   * @examplePrompt Set the target FAR to 2.5
+   * @examplePrompt Override the site area to 5000
+   * @examplePrompt Allow a 10 percent FAR deviation
+   *
+   * # Example
+   * ```ts
+   * const s = await snaptrude.program.areas.update({ targetFar: 2.5 })
+   * console.log(s.achievedFar, s.targetFar)
+   * ```
+   */
+  public abstract update(options?: {
+    targetFar?: number
+    siteArea?: number
+    deviation?: number
+  }): PluginApiReturn<PluginProgramAreasUpdateResult>
+
+  /**
+   * Force the area breakdown to recompute, then return the fresh summary.
+   *
+   * The engine recomputes the carpet / built-up / FAR totals live **only while the
+   * Area sidebar is open**. A plugin running with the sidebar closed can therefore
+   * read a stale — or never-computed — snapshot from {@linkcode
+   * PluginProgramAreasApi.get} / {@linkcode PluginProgramAreasApi.list}. Call
+   * `refresh` first to guarantee those reads reflect the current model. It is a
+   * read (no write gate) — it recomputes derived totals, it does not change the model.
+   *
+   * **Cost:** a full pass over every space, floor and mass in the active structure.
+   * Not free on large models — call it once before a batch of reads, not per read.
+   *
+   * @returns The freshly-recomputed {@linkcode PluginProgramAreaSummary}.
+   *
+   * @examplePrompt Recompute the area totals before I read them
+   * @examplePrompt Refresh the FAR numbers
+   * @examplePrompt Make sure the area breakdown is up to date
+   *
+   * # Example
+   * ```ts
+   * const s = await snaptrude.program.areas.refresh()
+   * const { groups } = await snaptrude.program.areas.list("storeys") // now fresh
+   * console.log(s.builtUp, groups.length)
+   * ```
+   */
+  public abstract refresh(): PluginApiReturn<PluginProgramAreasRefreshResult>
+}
+
+/**
+ * The whole-program area / FAR summary. All area figures are in `areaUnit`;
+ * ratios (`achievedFar`, `targetFar`, `deviation`) are unitless.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `count` | `number` | Number of spaces in the program (a count, not an area) |
+ * | `hiddenCount` | `number` | Number of those spaces that are currently hidden |
+ * | `carpet` | `number` | Total **Net Internal Area** ("net") — Σ `NET`-classed spaces + floors — in `areaUnit` |
+ * | `builtUp` | `number` | Total **Gross External Area** ("gross") — Σ `GROSS`-classed spaces + slabs — in `areaUnit` |
+ * | `excluded` | `number` | Total **Excluded Area** — Σ `EXCLUDED`-classed spaces — in `areaUnit` |
+ * | `farBuiltUp` | `number` | Built-up area that counts toward FAR, in `areaUnit` |
+ * | `siteArea` | `number` | Site/plot area in `areaUnit` |
+ * | `achievedFar` | `number \| null` | Derived FAR (`farBuiltUp / siteArea`); `null` when site area or target FAR is unset |
+ * | `targetFar` | `number` | The target FAR goal (set via `update`) |
+ * | `deviation` | `number` | Allowed FAR deviation, as a percentage |
+ * | `areaUnit` | `"ft2" \| "m2"` | The unit every area figure above is reported in |
+ */
+export const PluginProgramAreaSummary = z.object({
+  count: z.number().int(),
+  hiddenCount: z.number().int(),
+  carpet: z.number(),
+  builtUp: z.number(),
+  excluded: z.number(),
+  farBuiltUp: z.number(),
+  siteArea: z.number(),
+  achievedFar: z.number().nullable(),
+  targetFar: z.number(),
+  deviation: z.number(),
+  areaUnit: PluginAreaUnit,
+})
+export type PluginProgramAreaSummary = z.infer<typeof PluginProgramAreaSummary>
+
+/**
+ * One bucket of the area rollup. Carpet / built-up / excluded figures are in the
+ * program's area unit (see {@linkcode PluginProgramAreaSummary.areaUnit});
+ * `targetArea` is in `targetUnit`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groupId` | `string` | Stable id of the group (e.g. storey id, department id) |
+ * | `name` | `string` | Display name of the group |
+ * | `color` | `string` | CSS hex color string for the group |
+ * | `carpet` | `number` | Net Internal Area ("net") for this group |
+ * | `builtUp` | `number` | Gross External Area ("gross") for this group |
+ * | `excluded` | `number` | Excluded area for this group |
+ * | `count` | `number` | Number of spaces in this group |
+ * | `targetArea` | `number` | Target area for this group, in `targetUnit` |
+ * | `targetUnit` | `"ft2" \| "m2"` | The unit `targetArea` is reported in |
+ */
+export const PluginProgramAreaGroup = z.object({
+  groupId: z.string(),
+  name: z.string(),
+  color: z.string(),
+  carpet: z.number(),
+  builtUp: z.number(),
+  excluded: z.number(),
+  count: z.number().int(),
+  targetArea: z.number(),
+  targetUnit: PluginAreaUnit,
+})
+export type PluginProgramAreaGroup = z.infer<typeof PluginProgramAreaGroup>
+
+/**
+ * A single space within an area group. Area figures are in the program's area
+ * unit (see {@linkcode PluginProgramAreaSummary.areaUnit}).
+ *
+ * `areaClass` is the space's effective classification — it decides which of the
+ * three buckets the space's whole footprint lands in: `NET` → `carpet` ("net"),
+ * `GROSS` → `builtUp` ("gross"), `EXCLUDED` → `excluded`. So for any one member
+ * exactly one of `carpet` / `builtUp` / `excluded` is non-zero.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `ComponentHandle` | `Component.id` of the space (never a mesh handle) |
+ * | `label` | `string` | Display label of the space |
+ * | `areaClass` | {@linkcode PluginAreaClass} | Effective area class — `"NET"` (→ `carpet`), `"GROSS"` (→ `builtUp`), or `"EXCLUDED"` |
+ * | `carpet` | `number` | Net area of the space (non-zero when `areaClass` is `"NET"`) |
+ * | `builtUp` | `number` | Gross area of the space (non-zero when `areaClass` is `"GROSS"`) |
+ * | `excluded` | `number` | Excluded area of the space (non-zero when `areaClass` is `"EXCLUDED"`) |
+ * | `isVisible` | `boolean` | Whether the space is currently visible |
+ */
+export const PluginProgramAreaMember = z.object({
+  id: ComponentHandle,
+  label: z.string(),
+  areaClass: PluginAreaClass,
+  carpet: z.number(),
+  builtUp: z.number(),
+  excluded: z.number(),
+  isVisible: z.boolean(),
+})
+export type PluginProgramAreaMember = z.infer<typeof PluginProgramAreaMember>
+
+/** The facet to group the area rollup by. */
+export const PluginProgramAreaGroupBy = z.enum([
+  "labels",
+  "storeys",
+  "buildings",
+  "departments",
+  "tagCategories",
+])
+export type PluginProgramAreaGroupBy = z.infer<typeof PluginProgramAreaGroupBy>
+
+/** Result of {@linkcode PluginProgramAreasApi.get} — the program area summary. */
+export const PluginProgramAreasGetResult = PluginProgramAreaSummary
+export type PluginProgramAreasGetResult = z.infer<
+  typeof PluginProgramAreasGetResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramAreasApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groupBy` | {@linkcode PluginProgramAreaGroupBy} | The facet to group by |
+ * | `categoryId` | `string \| undefined` | Tag category to group by; required when `groupBy` is `"tagCategories"` |
+ */
+export const PluginProgramAreasListArgs = z
+  .object({
+    groupBy: PluginProgramAreaGroupBy,
+    categoryId: z.string().optional(),
+  })
+  .refine((v) => v.groupBy !== "tagCategories" || v.categoryId != null, {
+    message: 'categoryId is required when groupBy is "tagCategories"',
+  })
+export type PluginProgramAreasListArgs = z.infer<
+  typeof PluginProgramAreasListArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramAreasApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groups` | {@linkcode PluginProgramAreaGroup}`[]` | The area buckets (empty when the program has no spaces) |
+ */
+export const PluginProgramAreasListResult = z.object({
+  groups: z.array(PluginProgramAreaGroup),
+})
+export type PluginProgramAreasListResult = z.infer<
+  typeof PluginProgramAreasListResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramAreasApi.listMembers}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groupBy` | {@linkcode PluginProgramAreaGroupBy} | The facet the group came from |
+ * | `groupId` | `string` | The id of the group to expand |
+ * | `categoryId` | `string \| undefined` | Tag category context; required when `groupBy` is `"tagCategories"` |
+ */
+export const PluginProgramAreasListMembersArgs = z
+  .object({
+    groupBy: PluginProgramAreaGroupBy,
+    groupId: z.string(),
+    categoryId: z.string().optional(),
+  })
+  .refine((v) => v.groupBy !== "tagCategories" || v.categoryId != null, {
+    message: 'categoryId is required when groupBy is "tagCategories"',
+  })
+export type PluginProgramAreasListMembersArgs = z.infer<
+  typeof PluginProgramAreasListMembersArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramAreasApi.listMembers}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `members` | {@linkcode PluginProgramAreaMember}`[]` | The group's member spaces (empty when missing or empty) |
+ */
+export const PluginProgramAreasListMembersResult = z.object({
+  members: z.array(PluginProgramAreaMember),
+})
+export type PluginProgramAreasListMembersResult = z.infer<
+  typeof PluginProgramAreasListMembersResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramAreasApi.update}. Sparse — only the
+ * provided fields are changed.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `targetFar` | `number \| undefined` | New target FAR (≥ 0) |
+ * | `siteArea` | `number \| undefined` | Site-area override (> 0), in the program's area unit |
+ * | `deviation` | `number \| undefined` | Allowed FAR deviation percentage (0–100) |
+ */
+export const PluginProgramAreasUpdateArgs = z.object({
+  targetFar: z.number().min(0).optional(),
+  siteArea: z.number().positive().optional(),
+  deviation: z.number().min(0).max(100).optional(),
+})
+export type PluginProgramAreasUpdateArgs = z.infer<
+  typeof PluginProgramAreasUpdateArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramAreasApi.update} — the recomputed program
+ * area summary.
+ */
+export const PluginProgramAreasUpdateResult = PluginProgramAreaSummary
+export type PluginProgramAreasUpdateResult = z.infer<
+  typeof PluginProgramAreasUpdateResult
+>
+
+/**
+ * Result of {@linkcode PluginProgramAreasApi.refresh} — the freshly-recomputed
+ * program area summary.
+ */
+export const PluginProgramAreasRefreshResult = PluginProgramAreaSummary
+export type PluginProgramAreasRefreshResult = z.infer<
+  typeof PluginProgramAreasRefreshResult
+>