@snaptrude/plugin-core 0.0.0-dev-20260708130115 → 0.0.0-dev-20260827135706

package/src/api/program/areas.ts

@@ -1,6 +1,7 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
 import { PluginAreaUnit } from "./metrics"
+import { PluginAreaClass } from "../entity/space"
 import { ComponentHandle } from "../../handles"
 
 /**
@@ -12,15 +13,30 @@ import { ComponentHandle } from "../../handles"
  * 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. The write member typed as optional
- * (`?`) is **authored ahead of the host** — declared so plugins and codegen can
- * see the shape, but kept out of the discovery manifest until the host lands it
- * (at which point it is promoted to a required `abstract` member).
+ * 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`.
  */
@@ -38,6 +54,8 @@ export abstract class PluginProgramAreasApi {
    *
    * @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?
    *
@@ -62,6 +80,7 @@ export abstract class PluginProgramAreasApi {
    *   (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
    *
@@ -92,6 +111,7 @@ export abstract class PluginProgramAreasApi {
    *   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
    *
@@ -114,6 +134,13 @@ export abstract class PluginProgramAreasApi {
    * 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}.
@@ -129,9 +156,39 @@ export abstract class PluginProgramAreasApi {
    * console.log(s.achievedFar, s.targetFar)
    * ```
    */
-  public abstract update(
-    options?: { targetFar?: number; siteArea?: number; deviation?: number },
-  ): PluginApiReturn<PluginProgramAreasUpdateResult>
+  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>
 }
 
 /**
@@ -142,9 +199,9 @@ export abstract class PluginProgramAreasApi {
  * |---|---|---|
  * | `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 carpet area in `areaUnit` |
- * | `builtUp` | `number` | Total built-up area in `areaUnit` |
- * | `excluded` | `number` | Total excluded area in `areaUnit` |
+ * | `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 |
@@ -177,8 +234,8 @@ export type PluginProgramAreaSummary = z.infer<typeof PluginProgramAreaSummary>
  * | `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` | Carpet area for this group |
- * | `builtUp` | `number` | Built-up area for this 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` |
@@ -201,18 +258,25 @@ 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 |
- * | `carpet` | `number` | Carpet area of the space |
- * | `builtUp` | `number` | Built-up area of the space |
- * | `excluded` | `number` | Excluded area 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(),
@@ -333,3 +397,12 @@ 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
+>

package/src/api/program/cores.ts

@@ -5,13 +5,9 @@ import { PluginApiReturn } from "../../types"
  * Program cores — the building's vertical-circulation cores (lift / stair / shaft
  * shells).
  *
- * Read the cores in the scene, test whether a space is a core, and trigger core
- * generation from a layout. `create` is a **thin trigger**: the program hands a
- * core layout to the core-generation engine, which authors the geometry — the
- * core geometry itself is owned by the geometry layer, not here (the exact
- * layout ↔ engine payload is coordinated with the geometry owner).
- *
- * `list`/`isCore` are reads; `create` triggers generation.
+ * Read the cores in the scene and test whether a space is a core. Both are reads;
+ * there is no core-generation trigger on this surface (core geometry is owned by
+ * the geometry layer, not here).
  *
  * Accessed via `snaptrude.program.cores`.
  */
@@ -52,37 +48,6 @@ export abstract class PluginProgramCoresApi {
    * ```
    */
   public abstract isCore(id: string): PluginApiReturn<boolean>
-
-  /**
-   * Generate core geometry from a layout (thin trigger).
-   *
-   * Hands the core layout to the core-generation engine and returns how many core
-   * elements were created. The geometry is authored by the engine, not here.
-   * _(Authored ahead — optional until the host's geometry adapter lands; the
-   * reads {@linkcode PluginProgramCoresApi.list}/{@linkcode PluginProgramCoresApi.isCore}
-   * are live.)_
-   *
-   * @param cores - The {@linkcode PluginProgramCoreSpec} layout of cores to
-   *   generate.
-   * @param lengthUnit - Unit of the spec dimensions (default project unit).
-   * @returns A {@linkcode PluginProgramCoresCreateResult} with the created count.
-   * @throws If the layout could not be realized.
-   *
-   * @examplePrompt Generate the building cores from this layout
-   * @examplePrompt Place the elevator and stair cores
-   * @examplePrompt Create the service core shells
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.program.cores.create([
-   *   { type: "lift", position: { x: 0, y: 0, z: 0 }, width: 3, depth: 4 },
-   * ])
-   * ```
-   */
-  public create?: (
-    cores: PluginProgramCoreSpec[],
-    lengthUnit?: "mm" | "m" | "ft",
-  ) => PluginApiReturn<PluginProgramCoresCreateResult>
 }
 
 /**
@@ -116,56 +81,3 @@ export const PluginProgramCoresIsCoreArgs = z.object({
 export type PluginProgramCoresIsCoreArgs = z.infer<
   typeof PluginProgramCoresIsCoreArgs
 >
-
-/**
- * One core to generate. The geometry layer interprets this layout (the exact
- * fields are coordinated with the geometry owner).
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `type` | `string \| undefined` | Core kind (e.g. `"lift"`, `"stair"`, `"shaft"`) |
- * | `position` | `{ x; y; z }` | Base position of the core |
- * | `width` | `number` | Core width, in `lengthUnit` |
- * | `depth` | `number` | Core depth, in `lengthUnit` |
- * | `fromStorey` | `number \| undefined` | First storey the core spans |
- * | `toStorey` | `number \| undefined` | Last storey the core spans |
- */
-export const PluginProgramCoreSpec = z.object({
-  type: z.string().optional(),
-  position: z.object({ x: z.number(), y: z.number(), z: z.number() }),
-  width: z.number(),
-  depth: z.number(),
-  fromStorey: z.number().optional(),
-  toStorey: z.number().optional(),
-})
-export type PluginProgramCoreSpec = z.infer<typeof PluginProgramCoreSpec>
-
-/**
- * Arguments for {@linkcode PluginProgramCoresApi.create}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `cores` | {@linkcode PluginProgramCoreSpec}`[]` | The cores to generate |
- * | `lengthUnit` | `"mm" \| "m" \| "ft" \| undefined` | Unit of the spec dimensions (default project unit) |
- */
-export const PluginProgramCoresCreateArgs = z.object({
-  cores: z.array(PluginProgramCoreSpec),
-  lengthUnit: z.enum(["mm", "m", "ft"]).optional(),
-})
-export type PluginProgramCoresCreateArgs = z.infer<
-  typeof PluginProgramCoresCreateArgs
->
-
-/**
- * Result of {@linkcode PluginProgramCoresApi.create}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `createdCount` | `number` | Number of core elements created |
- */
-export const PluginProgramCoresCreateResult = z.object({
-  createdCount: z.number(),
-})
-export type PluginProgramCoresCreateResult = z.infer<
-  typeof PluginProgramCoresCreateResult
->

package/src/api/program/index.ts

@@ -19,19 +19,14 @@ import { PluginProgramAreasApi } from "./areas"
  *
  * - {@linkcode PluginProgramApi.departments} — Read & edit program departments (groupings + targets)
  * - {@linkcode PluginProgramApi.adjacency} — Read & compute the department/space adjacency matrix
- * - {@linkcode PluginProgramApi.layout} — Arrange/pack spaces in the envelope (authored ahead)
+ * - {@linkcode PluginProgramApi.layout} — Arrange/pack spaces in the envelope
  * - {@linkcode PluginProgramApi.metrics} — Read the area-program summary
  * - {@linkcode PluginProgramApi.areas} — FAR / built-up-area rollup and groupings
  * - {@linkcode PluginProgramApi.spreadsheet} — Render program data to sheets and read it back
- * - {@linkcode PluginProgramApi.site} — Read the site/plot planning context
- * - {@linkcode PluginProgramApi.cores} — Read & trigger vertical-circulation cores
+ * - {@linkcode PluginProgramApi.site} — Read site/plot context and read/update Site Analysis
+ * - {@linkcode PluginProgramApi.cores} — Read & predicate vertical-circulation cores (reads only)
  * - {@linkcode PluginProgramApi.classification} — Classification catalog + display tags
  *
- * Sub-namespaces typed as optional (`?`) are **authored ahead of the host** —
- * declared so plugins and codegen can see the shape, but not required of host
- * implementations and kept out of the discovery manifest until the host lands
- * them (at which point they are promoted to required `abstract` members).
- *
  * Accessed via `snaptrude.program`.
  */
 export abstract class PluginProgramApi {
@@ -39,20 +34,17 @@ export abstract class PluginProgramApi {
   public abstract departments: PluginProgramDepartmentsApi
   /** Adjacency matrix — read & compute proximity relationships. See {@linkcode PluginProgramAdjacencyApi}. */
   public abstract adjacency: PluginProgramAdjacencyApi
-  /**
-   * Arrange/pack spaces in the envelope. See {@linkcode PluginProgramLayoutApi}.
-   * _(authored ahead — optional until the host lands it next increment.)_
-   */
-  public layout?: PluginProgramLayoutApi
+  /** Arrange/pack spaces in the envelope (async job family). See {@linkcode PluginProgramLayoutApi}. */
+  public abstract layout: PluginProgramLayoutApi
   /** Area-program summary — targets vs allocated area. See {@linkcode PluginProgramMetricsApi}. */
   public abstract metrics: PluginProgramMetricsApi
   /** FAR / built-up-area rollup and groupings. See {@linkcode PluginProgramAreasApi}. */
   public abstract areas: PluginProgramAreasApi
   /** Spreadsheet reports — render tables to sheets, export, list, read back. See {@linkcode PluginProgramSpreadsheetApi}. */
   public abstract spreadsheet: PluginProgramSpreadsheetApi
-  /** Site/plot planning context — total area, parcel footprints, geo rings. See {@linkcode PluginProgramSiteApi}. */
+  /** Site/plot context and persisted Site Analysis. See {@linkcode PluginProgramSiteApi}. */
   public abstract site: PluginProgramSiteApi
-  /** Vertical-circulation cores — read & predicate (live); generation trigger is optional. See {@linkcode PluginProgramCoresApi}. */
+  /** Vertical-circulation cores — read & predicate (reads only). See {@linkcode PluginProgramCoresApi}. */
   public abstract cores: PluginProgramCoresApi
   /** Classification catalog (space/area/mass types) + display tags. See {@linkcode PluginProgramClassificationApi}. */
   public abstract classification: PluginProgramClassificationApi