@snaptrude/plugin-core 0.3.0 → 0.5.0

package/src/api/program/index.ts

@@ -0,0 +1,71 @@
+import { PluginProgramDepartmentsApi } from "./departments"
+import { PluginProgramAdjacencyApi } from "./adjacency"
+import { PluginProgramLayoutApi } from "./layout"
+import { PluginProgramMetricsApi } from "./metrics"
+import { PluginProgramSpreadsheetApi } from "./spreadsheet"
+import { PluginProgramSiteApi } from "./site"
+import { PluginProgramCoresApi } from "./cores"
+import { PluginProgramClassificationApi } from "./classification"
+import { PluginProgramAreasApi } from "./areas"
+
+/**
+ * Program-mode planning APIs.
+ *
+ * The program is the space-planning layer: department groupings with area targets,
+ * the metrics that track allocated area against those targets, and the reports
+ * that render program/takeoff data to spreadsheet sheets. Reads describe the
+ * *plan* (intent + targets); the geometry that realizes the plan is authored
+ * through the geometry namespaces.
+ *
+ * - {@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.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.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 {
+  /** Program departments — groupings, area targets, and space assignment. See {@linkcode PluginProgramDepartmentsApi}. */
+  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
+  /** 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}. */
+  public abstract site: PluginProgramSiteApi
+  /** Vertical-circulation cores — read & predicate (live); generation trigger is optional. See {@linkcode PluginProgramCoresApi}. */
+  public abstract cores: PluginProgramCoresApi
+  /** Classification catalog (space/area/mass types) + display tags. See {@linkcode PluginProgramClassificationApi}. */
+  public abstract classification: PluginProgramClassificationApi
+
+  constructor() {}
+}
+
+export * from "./departments"
+export * from "./adjacency"
+export * from "./layout"
+export * from "./metrics"
+export * from "./spreadsheet"
+export * from "./site"
+export * from "./cores"
+export * from "./classification"
+export * from "./areas"

package/src/api/program/layout.ts

@@ -0,0 +1,68 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Program layout — arrange and pack spaces inside the envelope.
+ *
+ * These wrap the product's **Arrange in envelope** / **Pack in envelope**
+ * tools (engine: `Planner.pack_arrange` in the react host) — stages two and
+ * three of the space-planning workflow that starts with
+ * {@linkcode PluginProgramAdjacencyApi} (`program.adjacency`).
+ *
+ * _(Authored ahead — both methods are optional until the host lands them in
+ * the next increment, and are kept out of the discovery manifest until then.)_
+ *
+ * Accessed via `snaptrude.program.layout`.
+ */
+export abstract class PluginProgramLayoutApi {
+  constructor() {}
+
+  /**
+   * Arrange the spaces inside the envelope using the computed adjacency data.
+   * _(Authored ahead — optional until the host lands.)_
+   *
+   * @examplePrompt Arrange the rooms in the envelope
+   * @examplePrompt Lay out the departments inside the building envelope
+   * @examplePrompt Auto-arrange the program spaces
+   *
+   * # Example
+   * ```ts
+   * const { success, error } = await snaptrude.program.layout.arrange()
+   * if (!success) console.log("Arrange failed:", error)
+   * ```
+   */
+  public arrange?: () => PluginApiReturn<PluginProgramLayoutRunResult>
+
+  /**
+   * Pack the spaces into the envelope (a tighter fit than arrange).
+   * _(Authored ahead — optional until the host lands.)_
+   *
+   * @examplePrompt Pack the rooms into the envelope
+   * @examplePrompt Fit the program spaces tightly into the building
+   * @examplePrompt Run pack-in-envelope on this storey
+   *
+   * # Example
+   * ```ts
+   * const { success, error } = await snaptrude.program.layout.pack()
+   * if (!success) console.log("Pack failed:", error)
+   * ```
+   */
+  public pack?: () => PluginApiReturn<PluginProgramLayoutRunResult>
+}
+
+/**
+ * Result of {@linkcode PluginProgramLayoutApi.arrange} /
+ * {@linkcode PluginProgramLayoutApi.pack}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `success` | `boolean` | Whether the layout run completed |
+ * | `error` | `string \| undefined` | Failure reason when `success` is `false` |
+ */
+export const PluginProgramLayoutRunResult = z.object({
+  success: z.boolean(),
+  error: z.string().optional(),
+})
+export type PluginProgramLayoutRunResult = z.infer<
+  typeof PluginProgramLayoutRunResult
+>

package/src/api/program/metrics.ts

@@ -0,0 +1,120 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Program metrics — the area-program summary of the active project.
+ *
+ * Aggregate planning numbers: total target versus allocated area, plus a
+ * per-department breakdown. This is the program-mode "am I hitting my area
+ * targets?" read; per-entity geometry measurements (a single space's area,
+ * volume, bounding box) live under the geometry namespaces, not here.
+ *
+ * Every area is reported in the summary's `units` (ft² or m²). This is a read:
+ * it never throws and returns an empty breakdown with zero totals when the
+ * project has no program.
+ *
+ * Accessed via `snaptrude.program.metrics`.
+ */
+export abstract class PluginProgramMetricsApi {
+  constructor() {}
+
+  /**
+   * Get the area-program summary for the active project.
+   *
+   * @returns A {@linkcode PluginProgramMetricsSummary} with project-level totals
+   *   and a per-department area breakdown.
+   *
+   * @examplePrompt How much area have I allocated versus my targets?
+   * @examplePrompt Give me the program area summary
+   * @examplePrompt Which departments are over or under their target area?
+   * @examplePrompt What's the total built area in the program?
+   * @examplePrompt Show the area breakdown per department
+   * @examplePrompt Am I within my area program?
+   *
+   * # Example
+   * ```ts
+   * const m = await snaptrude.program.metrics.get()
+   * console.log(`${m.totalAllocatedArea} / ${m.totalTargetArea} ${m.units}`)
+   * console.log("unassigned:", m.unassignedArea)
+   * for (const d of m.departments) {
+   *   console.log(d.name, d.allocatedArea, d.targetArea)
+   * }
+   * ```
+   */
+  public abstract get(): PluginApiReturn<PluginProgramMetricsSummary>
+}
+
+/**
+ * The unit areas are reported in: square feet (`"ft2"`) or square metres (`"m2"`).
+ *
+ * **Area-units convention (applies to every area-returning method).** A result
+ * carries exactly one `units` field, at the **top level of the value the method
+ * returns**: on the response **envelope** for `list`/multi/composite results, and
+ * on the **record itself** only for a single `.get` that returns a bare record.
+ * Inner/leaf records never repeat it.
+ */
+export const PluginAreaUnit = z.enum(["ft2", "m2"])
+export type PluginAreaUnit = z.infer<typeof PluginAreaUnit>
+
+/**
+ * Per-department area figures within the program summary. Areas are in the
+ * enclosing {@linkcode PluginProgramMetricsSummary}'s `units`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `departmentId` | `string` | Department id |
+ * | `name` | `string` | Department name |
+ * | `targetArea` | `number \| null` | Target area in project units, or `null` if no target is set |
+ * | `allocatedArea` | `number` | Area currently allocated to this department, in project units |
+ */
+export const PluginProgramDepartmentMetric = z.object({
+  departmentId: z.string(),
+  name: z.string(),
+  targetArea: z.number().nullable(),
+  allocatedArea: z.number(),
+})
+export type PluginProgramDepartmentMetric = z.infer<
+  typeof PluginProgramDepartmentMetric
+>
+
+/**
+ * Result of {@linkcode PluginProgramMetricsApi.get}.
+ *
+ * Reconciliation invariant: `totalAllocatedArea === unassignedArea` plus the sum
+ * of every `departments[].allocatedArea`. `totalTargetArea` is the sum of every
+ * `departments[].targetArea` (a `null` target counts as 0); unassigned area has
+ * no target. Every area is in `units`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `units` | `"ft2" \| "m2"` | The unit every area in this summary is reported in |
+ * | `totalTargetArea` | `number` | Sum of all department target areas |
+ * | `totalAllocatedArea` | `number` | Total allocated area = departments + `unassignedArea` |
+ * | `unassignedArea` | `number` | Allocated area not attributed to any listed department (site/unassigned) — the delta that reconciles the total |
+ * | `departments` | {@linkcode PluginProgramDepartmentMetric}`[]` | Per-department area breakdown |
+ */
+export const PluginProgramMetricsSummary = z
+  .object({
+    units: PluginAreaUnit,
+    totalTargetArea: z.number(),
+    totalAllocatedArea: z.number(),
+    unassignedArea: z.number(),
+    departments: z.array(PluginProgramDepartmentMetric),
+  })
+  .refine(
+    (s) => {
+      const summed =
+        s.unassignedArea +
+        s.departments.reduce((acc, d) => acc + d.allocatedArea, 0)
+      // Reconciliation tolerance: 0.01 absolute or 0.01% relative, for float drift.
+      const tolerance = Math.max(0.01, Math.abs(s.totalAllocatedArea) * 1e-4)
+      return Math.abs(s.totalAllocatedArea - summed) <= tolerance
+    },
+    {
+      message:
+        "totalAllocatedArea must equal unassignedArea + the sum of departments[].allocatedArea",
+    },
+  )
+export type PluginProgramMetricsSummary = z.infer<
+  typeof PluginProgramMetricsSummary
+>

package/src/api/program/site.ts

@@ -0,0 +1,326 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+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
+ * (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.
+ *
+ * All methods are reads: they return plain records and never throw — `get`
+ * returns an empty snapshot (zero totals) when there is no site, and the `list`
+ * methods return `[]`.
+ *
+ * Accessed via `snaptrude.program.site`.
+ */
+export abstract class PluginProgramSiteApi {
+  constructor() {}
+
+  /**
+   * Get a snapshot of the project site.
+   *
+   * @returns A {@linkcode PluginProgramSiteSnapshot} with the total site area,
+   *   parcel count, and each parcel's footprint. Empty (zero totals, no
+   *   parcels) when the project has no site.
+   *
+   * @examplePrompt What is my total site area?
+   * @examplePrompt Give me a summary of the site
+   * @examplePrompt How many site parcels are on the canvas?
+   * @examplePrompt Show the site footprint and its area
+   * @examplePrompt How big is the plot I'm building on?
+   *
+   * # Example
+   * ```ts
+   * const site = await snaptrude.program.site.get()
+   * console.log(`${site.totalArea} ${site.units} across ${site.polygonCount} parcels`)
+   * ```
+   */
+  public abstract get(): PluginApiReturn<PluginProgramSiteSnapshot>
+
+  /**
+   * Get just the total site area.
+   *
+   * A fast single-metric read — the same number as
+   * {@linkcode PluginProgramSiteSnapshot.totalArea}, without computing the
+   * per-parcel footprints.
+   *
+   * @returns A {@linkcode PluginProgramSiteAreaResult} with the total `area` and
+   *   its `units` (`0` when there is no site).
+   *
+   * @examplePrompt What's the total site area?
+   * @examplePrompt How big is my plot in square metres?
+   * @examplePrompt Total parcel area on the site
+   *
+   * # Example
+   * ```ts
+   * const { area, units } = await snaptrude.program.site.getArea()
+   * ```
+   */
+  public abstract getArea(): PluginApiReturn<PluginProgramSiteAreaResult>
+
+  /**
+   * List the site parcels with their footprints (in scene coordinates).
+   *
+   * @returns A {@linkcode PluginProgramSiteListPolygonsResult} with each parcel's
+   *   id, area, label, and 2D footprint (XZ ground-plane points). Empty when the
+   *   project has no site.
+   *
+   * @examplePrompt List every site parcel
+   * @examplePrompt Show me each plot's footprint
+   * @examplePrompt Which site parcels are largest?
+   * @examplePrompt Get the boundary points of the site polygons
+   *
+   * # Example
+   * ```ts
+   * const { polygons, units } = await snaptrude.program.site.listPolygons()
+   * for (const p of polygons) console.log(p.label, p.area, units, p.footprint.length)
+   * ```
+   */
+  public abstract listPolygons(): PluginApiReturn<PluginProgramSiteListPolygonsResult>
+
+  /**
+   * List the site parcels as geographic latitude/longitude rings.
+   *
+   * 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.
+   *
+   * @returns A {@linkcode PluginProgramSiteListGeoPolygonsResult} with one ring
+   *   of `{ lat, lng, alt }` points per parcel.
+   *
+   * @examplePrompt Give me the site polygons in latitude and longitude
+   * @examplePrompt Export the plot boundary as geo-coordinates
+   * @examplePrompt Where is the site located geographically?
+   * @examplePrompt Get the site parcels as lat/long rings
+   *
+   * # Example
+   * ```ts
+   * const { polygons } = await snaptrude.program.site.listGeoPolygons()
+   * const firstRing = polygons[0] // [{ lat, lng, alt }, ...]
+   * ```
+   */
+  public abstract listGeoPolygons(): PluginApiReturn<PluginProgramSiteListGeoPolygonsResult>
+
+  /**
+   * Get the geo-referenced terrain context of the site.
+   *
+   * The map center and bounds, the terrain size in metres, the effective zoom,
+   * and each parcel's geographic footprint and area — the context used for site
+   * analysis. Returns `null` when the project is not geo-located on terrain.
+   *
+   * @returns A {@linkcode PluginProgramSiteContext}, or `null`.
+   *
+   * @examplePrompt What's the site's map center and bounds?
+   * @examplePrompt How wide is the terrain in metres?
+   * @examplePrompt Give me the parcel geometry and areas
+   * @examplePrompt Where is the site located on the map?
+   *
+   * # Example
+   * ```ts
+   * const ctx = await snaptrude.program.site.getContext()
+   * if (ctx) console.log(ctx.center, ctx.widthInM)
+   * ```
+   */
+  public abstract getContext(): PluginApiReturn<PluginProgramSiteContextResult>
+}
+
+/**
+ * A 2D ground-plane point of a site parcel footprint, in scene coordinates
+ * (metres on the project's XZ plane).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `x` | `number` | X coordinate (scene metres) |
+ * | `z` | `number` | Z coordinate (scene metres) |
+ */
+export const PluginSiteFootprintPoint = z.object({
+  x: z.number(),
+  z: z.number(),
+})
+export type PluginSiteFootprintPoint = z.infer<typeof PluginSiteFootprintPoint>
+
+/**
+ * A geographic point of a site parcel ring (WGS84).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `lat` | `number` | Latitude (degrees) |
+ * | `lng` | `number` | Longitude (degrees) |
+ * | `alt` | `number` | Altitude (metres) |
+ */
+export const PluginSiteGeoPoint = z.object({
+  lat: z.number(),
+  lng: z.number(),
+  alt: z.number(),
+})
+export type PluginSiteGeoPoint = z.infer<typeof PluginSiteGeoPoint>
+
+/**
+ * A single site parcel/polygon. Its `area` is in the enclosing result's `units`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Unique parcel/component id |
+ * | `area` | `number` | Footprint area, in the result's `units` |
+ * | `label` | `string` | Parcel label / room type (e.g. `"site"`) |
+ * | `footprint` | {@linkcode PluginSiteFootprintPoint}`[]` | 2D ground-plane boundary points |
+ */
+export const PluginSitePolygon = z.object({
+  id: z.string(),
+  area: z.number(),
+  label: z.string(),
+  footprint: z.array(PluginSiteFootprintPoint),
+})
+export type PluginSitePolygon = z.infer<typeof PluginSitePolygon>
+
+/**
+ * Result of {@linkcode PluginProgramSiteApi.get}. Per the area-units convention,
+ * `units` sits on this snapshot and every `area` below is reported in it.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `units` | `"ft2" \| "m2"` | The unit all areas in this snapshot are reported in |
+ * | `totalArea` | `number` | Total area of all site parcels |
+ * | `polygonCount` | `number` | Number of site parcels |
+ * | `polygons` | {@linkcode PluginSitePolygon}`[]` | Each site parcel with its footprint |
+ */
+export const PluginProgramSiteSnapshot = z.object({
+  units: PluginAreaUnit,
+  totalArea: z.number(),
+  polygonCount: z.number(),
+  polygons: z.array(PluginSitePolygon),
+})
+export type PluginProgramSiteSnapshot = z.infer<
+  typeof PluginProgramSiteSnapshot
+>
+
+/**
+ * Result of {@linkcode PluginProgramSiteApi.getArea}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `units` | `"ft2" \| "m2"` | The unit `area` is reported in |
+ * | `area` | `number` | Total site area |
+ */
+export const PluginProgramSiteAreaResult = z.object({
+  units: PluginAreaUnit,
+  area: z.number(),
+})
+export type PluginProgramSiteAreaResult = z.infer<
+  typeof PluginProgramSiteAreaResult
+>
+
+/**
+ * Result of {@linkcode PluginProgramSiteApi.listPolygons}. `units` sits on the
+ * response; each parcel's `area` is in it.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `units` | `"ft2" \| "m2"` | The unit every parcel `area` is reported in |
+ * | `polygons` | {@linkcode PluginSitePolygon}`[]` | All site parcels |
+ */
+export const PluginProgramSiteListPolygonsResult = z.object({
+  units: PluginAreaUnit,
+  polygons: z.array(PluginSitePolygon),
+})
+export type PluginProgramSiteListPolygonsResult = z.infer<
+  typeof PluginProgramSiteListPolygonsResult
+>
+
+/**
+ * Result of {@linkcode PluginProgramSiteApi.listGeoPolygons} — one ring of
+ * geographic points per parcel (`[]` when the project is not geo-located).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `polygons` | {@linkcode PluginSiteGeoPoint}`[][]` | One ring per parcel; each ring is a list of geographic points |
+ */
+export const PluginProgramSiteListGeoPolygonsResult = z.object({
+  polygons: z.array(z.array(PluginSiteGeoPoint)),
+})
+export type PluginProgramSiteListGeoPolygonsResult = z.infer<
+  typeof PluginProgramSiteListGeoPolygonsResult
+>
+
+/**
+ * A geographic latitude/longitude point (no altitude).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `lat` | `number` | Latitude (degrees) |
+ * | `lng` | `number` | Longitude (degrees) |
+ */
+export const PluginSiteLatLng = z.object({
+  lat: z.number(),
+  lng: z.number(),
+})
+export type PluginSiteLatLng = z.infer<typeof PluginSiteLatLng>
+
+/**
+ * Geographic bounds of the site terrain.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `north` | `number` | North latitude |
+ * | `south` | `number` | South latitude |
+ * | `east` | `number` | East longitude |
+ * | `west` | `number` | West longitude |
+ */
+export const PluginSiteBounds = z.object({
+  north: z.number(),
+  south: z.number(),
+  east: z.number(),
+  west: z.number(),
+})
+export type PluginSiteBounds = z.infer<typeof PluginSiteBounds>
+
+/**
+ * A site parcel in the terrain context — geographic footprint and area.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `footprint` | {@linkcode PluginSiteLatLng}`[]` | Geographic boundary points |
+ * | `area` | `number` | Parcel area (project area units) |
+ */
+export const PluginSiteContextParcel = z.object({
+  footprint: z.array(PluginSiteLatLng),
+  area: z.number(),
+})
+export type PluginSiteContextParcel = z.infer<typeof PluginSiteContextParcel>
+
+/**
+ * The geo-referenced terrain context of the site.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `center` | {@linkcode PluginSiteLatLng} | Map center |
+ * | `bounds` | {@linkcode PluginSiteBounds} | Terrain bounds |
+ * | `widthInM` | `number` | Terrain width in metres |
+ * | `heightInM` | `number` | Terrain height in metres |
+ * | `zoom` | `number` | Effective map zoom |
+ * | `parcels` | {@linkcode PluginSiteContextParcel}`[]` | Site parcels with geographic footprints |
+ */
+export const PluginProgramSiteContext = z.object({
+  center: PluginSiteLatLng,
+  bounds: PluginSiteBounds,
+  widthInM: z.number(),
+  heightInM: z.number(),
+  zoom: z.number(),
+  parcels: z.array(PluginSiteContextParcel),
+})
+export type PluginProgramSiteContext = z.infer<typeof PluginProgramSiteContext>
+
+/**
+ * Result of {@linkcode PluginProgramSiteApi.getContext} — the terrain context, or
+ * `null` when the project is not geo-located.
+ */
+export const PluginProgramSiteContextResult =
+  PluginProgramSiteContext.nullable()
+export type PluginProgramSiteContextResult = z.infer<
+  typeof PluginProgramSiteContextResult
+>