@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

package/dist/api/presentation/views.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"views.d.ts","sourceRoot":"","sources":["../../../src/api/presentation/views.ts"],"names":[],"mappings":"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"}

package/dist/api/program/adjacency.d.ts

@@ -0,0 +1,155 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../types";
+/**
+ * Program adjacency — the proximity relationships between departments or
+ * spaces.
+ *
+ * Adjacency is stage one of the product's space-planning workflow (compute →
+ * arrange → pack): the AI service scores which program elements need to be
+ * near each other, and the geometry contributes physical contact. Cell values:
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `2` | Direct — adjacency required |
+ * | `1` | Indirect — nearby preferred, or physical contact |
+ * | `-1` | Restricted — must NOT be adjacent |
+ * | `0` | No relationship — or adjacency was never computed |
+ *
+ * Zeros are ambiguous **by design** (the engine cannot distinguish "no
+ * relationship" from "never computed"): call
+ * {@linkcode PluginProgramAdjacencyApi.compute} first when you need fresh
+ * data. Persisted matrices auto-hydrate on scene load, so warm reads are the
+ * common case. The arrange/pack stages of the workflow live in
+ * {@linkcode PluginProgramLayoutApi} (`program.layout`).
+ *
+ * Accessed via `snaptrude.program.adjacency`.
+ */
+export declare abstract class PluginProgramAdjacencyApi {
+    constructor();
+    /**
+     * Read the adjacency matrix at the department or space level.
+     *
+     * Returns a square `matrix` whose rows/columns are aligned to `ids`
+     * (component ids). Pass `ids` to read a sub-matrix in that order; omit it to
+     * get every eligible element at that level. Cell values:
+     *
+     * | Value | Meaning |
+     * |---|---|
+     * | `2` | Direct — adjacency required |
+     * | `1` | Indirect — nearby preferred, or physical contact |
+     * | `-1` | Restricted — must NOT be adjacent |
+     * | `0` | No relationship — or adjacency was never computed |
+     *
+     * Zeros are ambiguous by design — call
+     * {@linkcode PluginProgramAdjacencyApi.compute} first for fresh data
+     * (persisted matrices auto-hydrate on scene load, so warm reads are the
+     * common case). Space-level relationships are computed within a storey:
+     * cross-storey pairs always read `0`. At the `department` level the result
+     * also carries `departmentIds`, a parallel array joining each row to the
+     * department entity ids returned by `program.departments.list` (the row
+     * `ids` are department-mass component ids, not department entity ids).
+     *
+     * @param level - Read the `"department"` or `"space"` matrix.
+     * @param ids - Component ids to read a sub-matrix for, in this order
+     *   (defaults to every eligible element at the level).
+     * @returns A {@linkcode PluginProgramAdjacencyGetMatrixResult} with `ids`,
+     *   the square `matrix`, and (at department level) `departmentIds`.
+     * @throws If an id is unknown or does not match the requested level.
+     *
+     * @examplePrompt Get the space adjacency matrix
+     * @examplePrompt Which departments must be adjacent?
+     * @examplePrompt Show the adjacency relationships between departments
+     * @examplePrompt Read the adjacency matrix for these spaces
+     * @examplePrompt Which rooms are restricted from being next to each other?
+     *
+     * # Example
+     * ```ts
+     * const { ids, matrix } = await snaptrude.program.adjacency.getMatrix("department")
+     * ```
+     */
+    abstract getMatrix(level: PluginAdjacencyLevel, ids?: string[]): PluginApiReturn<PluginProgramAdjacencyGetMatrixResult>;
+    /**
+     * Compute (or refresh) the adjacency data for the project.
+     *
+     * Runs the AI adjacency precompute and persists the result; a no-op when
+     * the stored data is already fresh. A real run takes **~2s at minimum**
+     * (engine pacing) plus the AI service round-trip. This is a write (it
+     * mutates and persists project analysis data), so it is blocked when plugin
+     * writes are disabled.
+     *
+     * @returns A {@linkcode PluginProgramAdjacencyComputeResult} —
+     *   `{ success: true }` when the data is fresh or the run completed;
+     *   `{ success: false, error }` when the AI service could not be reached.
+     *
+     * @examplePrompt Refresh adjacency analysis
+     * @examplePrompt Compute the adjacency matrix for this project
+     * @examplePrompt Recalculate which departments should be adjacent
+     *
+     * # Example
+     * ```ts
+     * const { success } = await snaptrude.program.adjacency.compute()
+     * if (success) {
+     *   const data = await snaptrude.program.adjacency.getMatrix("space")
+     * }
+     * ```
+     */
+    abstract compute(): PluginApiReturn<PluginProgramAdjacencyComputeResult>;
+}
+/**
+ * The level an adjacency matrix is read at.
+ *
+ * | Value | Description |
+ * |---|---|
+ * | `"department"` | One row/column per department mass |
+ * | `"space"` | One row/column per space (within a storey) |
+ */
+export declare const PluginAdjacencyLevel: z.ZodEnum<{
+    space: "space";
+    department: "department";
+}>;
+export type PluginAdjacencyLevel = z.infer<typeof PluginAdjacencyLevel>;
+/**
+ * Arguments for {@linkcode PluginProgramAdjacencyApi.getMatrix}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `level` | {@linkcode PluginAdjacencyLevel} | Read the `"department"` or `"space"` matrix |
+ * | `ids` | `string[] \| undefined` | Component ids to read a sub-matrix for, in this order (defaults to every eligible element at the level) |
+ */
+export declare const PluginProgramAdjacencyGetMatrixArgs: z.ZodObject<{
+    level: z.ZodEnum<{
+        space: "space";
+        department: "department";
+    }>;
+    ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type PluginProgramAdjacencyGetMatrixArgs = z.infer<typeof PluginProgramAdjacencyGetMatrixArgs>;
+/**
+ * Result of {@linkcode PluginProgramAdjacencyApi.getMatrix}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `ids` | `string[]` | Component ids, in matrix row/column order |
+ * | `departmentIds` | `(string \| null)[] \| undefined` | Department level only: parallel to `ids`, the department entity id each row belongs to (joinable against `program.departments.list`), `null` when unassigned |
+ * | `matrix` | `number[][]` | Square matrix aligned to `ids`; values in `{-1, 0, 1, 2}` |
+ */
+export declare const PluginProgramAdjacencyGetMatrixResult: z.ZodObject<{
+    ids: z.ZodArray<z.ZodString>;
+    departmentIds: z.ZodOptional<z.ZodArray<z.ZodNullable<z.ZodString>>>;
+    matrix: z.ZodArray<z.ZodArray<z.ZodNumber>>;
+}, z.core.$strip>;
+export type PluginProgramAdjacencyGetMatrixResult = z.infer<typeof PluginProgramAdjacencyGetMatrixResult>;
+/**
+ * Result of {@linkcode PluginProgramAdjacencyApi.compute}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `success` | `boolean` | `true` when the data is fresh or the run completed |
+ * | `error` | `string \| undefined` | Failure reason when `success` is `false` |
+ */
+export declare const PluginProgramAdjacencyComputeResult: z.ZodObject<{
+    success: z.ZodBoolean;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginProgramAdjacencyComputeResult = z.infer<typeof PluginProgramAdjacencyComputeResult>;
+//# sourceMappingURL=adjacency.d.ts.map

package/dist/api/program/adjacency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adjacency.d.ts","sourceRoot":"","sources":["../../../src/api/program/adjacency.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,8BAAsB,yBAAyB;;IAG7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;aACa,SAAS,CACvB,KAAK,EAAE,oBAAoB,EAC3B,GAAG,CAAC,EAAE,MAAM,EAAE,GACb,eAAe,CAAC,qCAAqC,CAAC;IAEzD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;aACa,OAAO,IAAI,eAAe,CAAC,mCAAmC,CAAC;CAChF;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB;;;EAAkC,CAAA;AACnE,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE;;;;;;;GAOG;AACH,eAAO,MAAM,mCAAmC;;;;;;iBAG9C,CAAA;AACF,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,KAAK,CACvD,OAAO,mCAAmC,CAC3C,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,qCAAqC;;;;iBAIhD,CAAA;AACF,MAAM,MAAM,qCAAqC,GAAG,CAAC,CAAC,KAAK,CACzD,OAAO,qCAAqC,CAC7C,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mCAAmC;;;iBAG9C,CAAA;AACF,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,KAAK,CACvD,OAAO,mCAAmC,CAC3C,CAAA"}

package/dist/api/program/areas.d.ts

@@ -0,0 +1,450 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../types";
+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 declare 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)
+     * ```
+     */
+    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)
+     * ```
+     */
+    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)
+     * ```
+     */
+    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)
+     * ```
+     */
+    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)
+     * ```
+     */
+    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 declare const PluginProgramAreaSummary: z.ZodObject<{
+    count: z.ZodNumber;
+    hiddenCount: z.ZodNumber;
+    carpet: z.ZodNumber;
+    builtUp: z.ZodNumber;
+    excluded: z.ZodNumber;
+    farBuiltUp: z.ZodNumber;
+    siteArea: z.ZodNumber;
+    achievedFar: z.ZodNullable<z.ZodNumber>;
+    targetFar: z.ZodNumber;
+    deviation: z.ZodNumber;
+    areaUnit: z.ZodEnum<{
+        ft2: "ft2";
+        m2: "m2";
+    }>;
+}, z.core.$strip>;
+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 declare const PluginProgramAreaGroup: z.ZodObject<{
+    groupId: z.ZodString;
+    name: z.ZodString;
+    color: z.ZodString;
+    carpet: z.ZodNumber;
+    builtUp: z.ZodNumber;
+    excluded: z.ZodNumber;
+    count: z.ZodNumber;
+    targetArea: z.ZodNumber;
+    targetUnit: z.ZodEnum<{
+        ft2: "ft2";
+        m2: "m2";
+    }>;
+}, z.core.$strip>;
+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 declare const PluginProgramAreaMember: z.ZodObject<{
+    id: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    label: z.ZodString;
+    areaClass: z.ZodEnum<{
+        NET: "NET";
+        GROSS: "GROSS";
+        EXCLUDED: "EXCLUDED";
+    }>;
+    carpet: z.ZodNumber;
+    builtUp: z.ZodNumber;
+    excluded: z.ZodNumber;
+    isVisible: z.ZodBoolean;
+}, z.core.$strip>;
+export type PluginProgramAreaMember = z.infer<typeof PluginProgramAreaMember>;
+/** The facet to group the area rollup by. */
+export declare const PluginProgramAreaGroupBy: z.ZodEnum<{
+    buildings: "buildings";
+    storeys: "storeys";
+    departments: "departments";
+    labels: "labels";
+    tagCategories: "tagCategories";
+}>;
+export type PluginProgramAreaGroupBy = z.infer<typeof PluginProgramAreaGroupBy>;
+/** Result of {@linkcode PluginProgramAreasApi.get} — the program area summary. */
+export declare const PluginProgramAreasGetResult: z.ZodObject<{
+    count: z.ZodNumber;
+    hiddenCount: z.ZodNumber;
+    carpet: z.ZodNumber;
+    builtUp: z.ZodNumber;
+    excluded: z.ZodNumber;
+    farBuiltUp: z.ZodNumber;
+    siteArea: z.ZodNumber;
+    achievedFar: z.ZodNullable<z.ZodNumber>;
+    targetFar: z.ZodNumber;
+    deviation: z.ZodNumber;
+    areaUnit: z.ZodEnum<{
+        ft2: "ft2";
+        m2: "m2";
+    }>;
+}, z.core.$strip>;
+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 declare const PluginProgramAreasListArgs: z.ZodObject<{
+    groupBy: z.ZodEnum<{
+        buildings: "buildings";
+        storeys: "storeys";
+        departments: "departments";
+        labels: "labels";
+        tagCategories: "tagCategories";
+    }>;
+    categoryId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+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 declare const PluginProgramAreasListResult: z.ZodObject<{
+    groups: z.ZodArray<z.ZodObject<{
+        groupId: z.ZodString;
+        name: z.ZodString;
+        color: z.ZodString;
+        carpet: z.ZodNumber;
+        builtUp: z.ZodNumber;
+        excluded: z.ZodNumber;
+        count: z.ZodNumber;
+        targetArea: z.ZodNumber;
+        targetUnit: z.ZodEnum<{
+            ft2: "ft2";
+            m2: "m2";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+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 declare const PluginProgramAreasListMembersArgs: z.ZodObject<{
+    groupBy: z.ZodEnum<{
+        buildings: "buildings";
+        storeys: "storeys";
+        departments: "departments";
+        labels: "labels";
+        tagCategories: "tagCategories";
+    }>;
+    groupId: z.ZodString;
+    categoryId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+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 declare const PluginProgramAreasListMembersResult: z.ZodObject<{
+    members: z.ZodArray<z.ZodObject<{
+        id: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+        label: z.ZodString;
+        areaClass: z.ZodEnum<{
+            NET: "NET";
+            GROSS: "GROSS";
+            EXCLUDED: "EXCLUDED";
+        }>;
+        carpet: z.ZodNumber;
+        builtUp: z.ZodNumber;
+        excluded: z.ZodNumber;
+        isVisible: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+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 declare const PluginProgramAreasUpdateArgs: z.ZodObject<{
+    targetFar: z.ZodOptional<z.ZodNumber>;
+    siteArea: z.ZodOptional<z.ZodNumber>;
+    deviation: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PluginProgramAreasUpdateArgs = z.infer<typeof PluginProgramAreasUpdateArgs>;
+/**
+ * Result of {@linkcode PluginProgramAreasApi.update} — the recomputed program
+ * area summary.
+ */
+export declare const PluginProgramAreasUpdateResult: z.ZodObject<{
+    count: z.ZodNumber;
+    hiddenCount: z.ZodNumber;
+    carpet: z.ZodNumber;
+    builtUp: z.ZodNumber;
+    excluded: z.ZodNumber;
+    farBuiltUp: z.ZodNumber;
+    siteArea: z.ZodNumber;
+    achievedFar: z.ZodNullable<z.ZodNumber>;
+    targetFar: z.ZodNumber;
+    deviation: z.ZodNumber;
+    areaUnit: z.ZodEnum<{
+        ft2: "ft2";
+        m2: "m2";
+    }>;
+}, z.core.$strip>;
+export type PluginProgramAreasUpdateResult = z.infer<typeof PluginProgramAreasUpdateResult>;
+/**
+ * Result of {@linkcode PluginProgramAreasApi.refresh} — the freshly-recomputed
+ * program area summary.
+ */
+export declare const PluginProgramAreasRefreshResult: z.ZodObject<{
+    count: z.ZodNumber;
+    hiddenCount: z.ZodNumber;
+    carpet: z.ZodNumber;
+    builtUp: z.ZodNumber;
+    excluded: z.ZodNumber;
+    farBuiltUp: z.ZodNumber;
+    siteArea: z.ZodNumber;
+    achievedFar: z.ZodNullable<z.ZodNumber>;
+    targetFar: z.ZodNumber;
+    deviation: z.ZodNumber;
+    areaUnit: z.ZodEnum<{
+        ft2: "ft2";
+        m2: "m2";
+    }>;
+}, z.core.$strip>;
+export type PluginProgramAreasRefreshResult = z.infer<typeof PluginProgramAreasRefreshResult>;
+//# sourceMappingURL=areas.d.ts.map

package/dist/api/program/areas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"areas.d.ts","sourceRoot":"","sources":["../../../src/api/program/areas.ts"],"names":[],"mappings":"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"}