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

package/src/api/program/site.ts

@@ -6,15 +6,21 @@ import { PluginAreaUnit } from "./metrics"
  * Program site — read the planning context of the project's site/plot.
  *
  * The **site** is the set of plot/parcel footprints the program is planned
- * against: their total area, per-parcel footprints (in scene XZ coordinates),
- * and — when the project is geo-located on terrain — their geographic
+ * against: their total area, per-parcel footprints (world XZ plan coordinates
+ * in Snaptrude units — the same plan space as a space's `planPoints`), and —
+ * when the project is geo-located on terrain — their geographic
  * (latitude/longitude) rings. This is the program-planning view of the site;
- * zoning numbers (setbacks, FAR/FSI, height limits) live in the site-analysis
- * sheet and are not read here.
+ * zoning numbers (FAR/FSI, height limits) live in the Site Analysis sheet and
+ * are available through `getSiteAnalysis`, not the site-context reads. One
+ * context exception is `listEdges`: it reads each parcel's per-edge
+ * front/side/rear classification and effective base setbacks, the same
+ * resolution the buildable-envelope setback pills show on canvas.
  *
- * 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 `[]`.
+ * Site context methods are total 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 `[]`. Site Analysis is the exception:
+ * `getSiteAnalysis` reads the active proposal's persisted analysis sheet and
+ * `updateSiteAnalysis` performs a safe merge/append write to that sheet.
  *
  * Accessed via `snaptrude.program.site`.
  */
@@ -64,7 +70,8 @@ export abstract class PluginProgramSiteApi {
   public abstract getArea(): PluginApiReturn<PluginProgramSiteAreaResult>
 
   /**
-   * List the site parcels with their footprints (in scene coordinates).
+   * List the site parcels with their footprints (world XZ plan coordinates,
+   * Snaptrude units).
    *
    * @returns A {@linkcode PluginProgramSiteListPolygonsResult} with each parcel's
    *   id, area, label, and 2D footprint (XZ ground-plane points). Empty when the
@@ -83,12 +90,53 @@ export abstract class PluginProgramSiteApi {
    */
   public abstract listPolygons(): PluginApiReturn<PluginProgramSiteListPolygonsResult>
 
+  /**
+   * List each site parcel's boundary edges with their front / side / rear
+   * classification — the same per-edge roles the buildable-envelope setback
+   * pills show on canvas, so a plugin can pick up the user's edge tagging
+   * without asking them to set it up again.
+   *
+   * Role resolution mirrors the canvas exactly: the user's per-edge overrides
+   * (set via the setback pills) win over the tangent heuristic
+   * (`roleSource: "override"` vs `"heuristic"`). `"street"` never appears — it
+   * resolves to `front`. When a parcel has a linked zoning buildable envelope,
+   * `setbackMeters` is the effective base setback of the edge (a per-edge
+   * exception when one exists, else the role's value); parcels without a
+   * zoning envelope classify by heuristic alone and report
+   * `setbackMeters: null`.
+   *
+   * Coordinates are **world meters** (`lengthUnit: "m"`) — unlike
+   * {@linkcode PluginProgramSiteApi.listPolygons} footprints, which are
+   * Snaptrude units. `edgeIndex` is keyed to the canonicalized (sanitized,
+   * CCW) boundary, the same index space the envelope's `edgeOverrides` use.
+   * `staleOverridesDropped: true` means the site was edited after the
+   * envelope was configured and the persisted overrides no longer align with
+   * the live boundary — the heuristic classification is reported instead.
+   *
+   * @returns A {@linkcode PluginProgramSiteListEdgesResult} with one entry per
+   *   parcel. Empty when the project has no site.
+   *
+   * @examplePrompt Which edge of my site is the front?
+   * @examplePrompt Read the front / side / rear edges of the plot
+   * @examplePrompt What setback applies to each site edge?
+   * @examplePrompt Get the site edges the way the setback pills show them
+   *
+   * # Example
+   * ```ts
+   * const { sites } = await snaptrude.program.site.listEdges()
+   * for (const site of sites)
+   *   for (const e of site.edges)
+   *     console.log(e.edgeIndex, e.role, e.roleSource, e.setbackMeters)
+   * ```
+   */
+  public abstract listEdges(): PluginApiReturn<PluginProgramSiteListEdgesResult>
+
   /**
    * 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.
+   * world-coordinate footprints that are always available.
    *
    * @returns A {@linkcode PluginProgramSiteListGeoPolygonsResult} with one ring
    *   of `{ lat, lng, alt }` points per parcel.
@@ -127,16 +175,242 @@ export abstract class PluginProgramSiteApi {
    * ```
    */
   public abstract getContext(): PluginApiReturn<PluginProgramSiteContextResult>
+
+  /**
+   * Get the project's geographic location.
+   *
+   * The latitude/longitude the site is geo-located at — the location the
+   * `analysis.*` sun and daylight studies compute against. Returns `null`
+   * when the project is not geo-located on terrain (there is no fallback
+   * location).
+   *
+   * Note the spelling: this result uses the full `{ latitude, longitude }`
+   * keys, while the older site reads
+   * ({@linkcode PluginProgramSiteApi.getContext},
+   * {@linkcode PluginProgramSiteApi.listGeoPolygons}) use the abbreviated
+   * `{ lat, lng }`.
+   *
+   * @returns A {@linkcode PluginProgramSiteLocationResult} —
+   *   `{ latitude, longitude }`, or `null` when the project has no
+   *   geo-located site.
+   *
+   * @examplePrompt What's the project's latitude and longitude?
+   * @examplePrompt Where is this site located?
+   * @examplePrompt Get the geographic coordinates of the project
+   *
+   * # Example
+   * ```ts
+   * const location = await snaptrude.program.site.getLocation()
+   * if (location) console.log(location.latitude, location.longitude)
+   * ```
+   */
+  public abstract getLocation(): PluginApiReturn<PluginProgramSiteLocationResult>
+
+  /**
+   * Get the site's true-north angle.
+   *
+   * The angle in degrees the model's north (the scene's +Z axis) is rotated
+   * from true north, derived from the terrain's rotation. `0` means the
+   * model is aligned to true north. Reported in `[0, 360)`,
+   * **clockwise-positive** viewed from above (Babylon's +Y rotation sign) —
+   * note this is the opposite sign convention to `design.transform.rotate`,
+   * where positive = CCW. Returns `null` when the project is not
+   * geo-located on terrain.
+   *
+   * @returns A {@linkcode PluginProgramSiteNorthAngleResult} — the angle in
+   *   degrees (`[0, 360)`, clockwise-positive), or `null` when the project
+   *   has no geo-located site.
+   *
+   * @examplePrompt What's the north angle of the site?
+   * @examplePrompt How far is the model rotated from true north?
+   * @examplePrompt Get the project's true north direction
+   *
+   * # Example
+   * ```ts
+   * const northAngle = await snaptrude.program.site.getNorthAngle()
+   * if (northAngle !== null) console.log(`${northAngle}° from true north`)
+   * ```
+   */
+  public abstract getNorthAngle(): PluginApiReturn<PluginProgramSiteNorthAngleResult>
+
+  /**
+   * Get the IANA timezone of the project's geographic location.
+   *
+   * The timezone identifier (e.g. `"America/New_York"`, `"Asia/Kolkata"`)
+   * looked up from the same geo-location
+   * {@linkcode PluginProgramSiteApi.getLocation} returns. Returns `null` when
+   * the project is not geo-located on terrain.
+   *
+   * @returns A {@linkcode PluginProgramSiteTimezoneResult} — the IANA timezone
+   *   id string, or `null` when the project has no geo-located site.
+   *
+   * @examplePrompt What timezone is this project in?
+   * @examplePrompt Get the site's IANA timezone
+   * @examplePrompt What's the local time zone at the project location?
+   * @examplePrompt Which timezone should I use for the sun study schedule?
+   *
+   * # Example
+   * ```ts
+   * const timezone = await snaptrude.program.site.getTimezone()
+   * if (timezone) console.log(`Project timezone: ${timezone}`)
+   * ```
+   */
+  public abstract getTimezone(): PluginApiReturn<PluginProgramSiteTimezoneResult>
+
+  /**
+   * Get the weather file resolved for the project site.
+   *
+   * A lightweight read of the EPW weather file the `analysis.*` sun and
+   * daylight studies compute against — its catalog id, station name, content
+   * checksum, and how it was selected. This is the same file (same
+   * `weatherFileId`) that {@linkcode PluginAnalysisWeatherApi.getSeries} reads
+   * rows from and that a daylight run echoes in its provenance. Returns `null`
+   * when the project has no geo-located site (no weather file to resolve).
+   *
+   * @returns A {@linkcode PluginProgramSiteWeatherResult} —
+   *   `{ weatherFileId, station, checksum, selectionMethod }`, or `null` when
+   *   the project has no geo-located site.
+   *
+   * @examplePrompt Which weather file is my project using?
+   * @examplePrompt What EPW station was resolved for this site?
+   * @examplePrompt Get the weather file id for the daylight analysis
+   *
+   * # Example
+   * ```ts
+   * const weather = await snaptrude.program.site.getWeather()
+   * if (weather) console.log(weather.station, weather.selectionMethod)
+   * ```
+   */
+  public abstract getWeather(): PluginApiReturn<PluginProgramSiteWeatherResult>
+
+  /**
+   * Read the persisted Site Analysis sheet for the active proposal.
+   *
+   * The read works without Program mode open. When a Program tab is open, the
+   * host first makes a best-effort attempt to flush its pending edits. The
+   * active proposal's sheet is preferred, with the base `"Site Analysis"`
+   * sheet as fallback. Returns `null` when no parseable sheet is persisted.
+   *
+   * @returns The persisted site location, polygon, and constraint rows, or
+   *   `null` when no Site Analysis data exists. This read never throws.
+   *
+   * @examplePrompt Read the current Site Analysis sheet
+   * @examplePrompt What zoning constraints are recorded for this proposal?
+   *
+   * # Example
+   * ```ts
+   * const analysis = await snaptrude.program.site.getSiteAnalysis()
+   * if (analysis) console.log(analysis.sheetName, analysis.rows)
+   * ```
+   */
+  public abstract getSiteAnalysis(): PluginApiReturn<PluginProgramSiteAnalysisResult>
+
+  /**
+   * Merge sourced site/zoning constraints into the active proposal's persisted
+   * Site Analysis sheet.
+   *
+   * Rows match by trimmed, case-insensitive Category + Description. Matched
+   * rows update only Quantity/Unit; unmatched rows append. Existing labels,
+   * formatting, and unrelated rows remain intact. There is deliberately no
+   * replace/reset mode — an appended duplicate row can NEVER be removed, so
+   * there is no "write now, fix later". Send only the rows that were actually
+   * sourced, ALWAYS call `getSiteAnalysis` first and reuse the sheet's exact
+   * labels, and never use `program.spreadsheet.setValues` for Site Analysis
+   * data — this method is the only correct writer. Check the result:
+   * `updatedRows` should account for every row that had a template match; an
+   * unexpected `appendedRows` usually means a label did not match the read's
+   * vocabulary.
+   *
+   * When Program mode is open, the host writes through the live sheet. Without
+   * a live tab it safely merges the persisted document. The call rejects rather
+   * than risk overwriting unflushed live edits or an unparseable existing sheet.
+   *
+   * @param rows - One or more sourced constraint rows to merge or append.
+   * @param options - Optional site location and JSON-encoded site polygon.
+   * @returns The target sheet name and merge counts.
+   * @throws PRECONDITION_FAILED when proposals exist but none is active, or
+   *   when live Program edits cannot be flushed safely.
+   *
+   * @examplePrompt Save these zoning constraints to Site Analysis
+   * @examplePrompt Update the FAR and setbacks in the Site Analysis sheet
+   *
+   * # Example
+   * ```ts
+   * const result = await snaptrude.program.site.updateSiteAnalysis([
+   *   { category: "FAR", description: "Floor Area Ratio", quantity: 3.5, unit: "ratio" },
+   *   { category: "Set backs", description: "Front setbacks", quantity: 6, unit: "m" },
+   * ])
+   * console.log(result.sheetName, result.updatedRows, result.appendedRows)
+   * ```
+   */
+  public abstract updateSiteAnalysis(
+    rows: PluginSiteAnalysisRow[],
+    options?: PluginSiteAnalysisUpdateOptions,
+  ): PluginApiReturn<PluginProgramSiteAnalysisUpdateResult>
 }
 
 /**
- * A 2D ground-plane point of a site parcel footprint, in scene coordinates
- * (metres on the project's XZ plane).
+ * A constraint row stored in the Site Analysis sheet. A `quantity` of `"-"`
+ * means the value is not recorded yet — never echo `"-"` back as a sourced
+ * value.
+ */
+export const PluginSiteAnalysisRow = z.object({
+  category: z.string().min(1),
+  description: z.string(),
+  quantity: z.union([z.string(), z.number()]),
+  unit: z.string(),
+})
+export type PluginSiteAnalysisRow = z.infer<typeof PluginSiteAnalysisRow>
+
+/**
+ * Optional site context persisted alongside Site Analysis constraint rows.
+ * `null` and `undefined` are both accepted as "no options".
+ */
+export const PluginSiteAnalysisUpdateOptions = z
+  .object({
+    siteLocation: z.object({ lat: z.number(), lng: z.number() }).optional(),
+    /** JSON-encoded polygon string written to the Site Polygon row. */
+    sitePolygon: z.string().optional(),
+  })
+  .nullish()
+export type PluginSiteAnalysisUpdateOptions = z.infer<
+  typeof PluginSiteAnalysisUpdateOptions
+>
+
+/** Persisted Site Analysis data for the active proposal. */
+export const PluginProgramSiteAnalysisResult = z
+  .object({
+    sheetName: z.string(),
+    siteLocation: z.object({ lat: z.number(), lng: z.number() }).nullable(),
+    sitePolygon: z.string().nullable(),
+    rows: z.array(PluginSiteAnalysisRow),
+  })
+  .nullable()
+export type PluginProgramSiteAnalysisResult = z.infer<
+  typeof PluginProgramSiteAnalysisResult
+>
+
+/** Result of a merge/append Site Analysis write. */
+export const PluginProgramSiteAnalysisUpdateResult = z.object({
+  sheetName: z.string(),
+  /** Constraint rows on the sheet after the write. */
+  rowCount: z.number(),
+  updatedRows: z.number(),
+  appendedRows: z.number(),
+})
+export type PluginProgramSiteAnalysisUpdateResult = z.infer<
+  typeof PluginProgramSiteAnalysisUpdateResult
+>
+
+/**
+ * A 2D ground-plane point of a site parcel footprint, in world XZ plan
+ * coordinates (Snaptrude units) — the same plan space as a space's
+ * `planPoints`, so site parcels overlay space footprints directly.
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `x` | `number` | X coordinate (scene metres) |
- * | `z` | `number` | Z coordinate (scene metres) |
+ * | `x` | `number` | X coordinate (world, Snaptrude units) |
+ * | `z` | `number` | Z coordinate (world, Snaptrude units) |
  */
 export const PluginSiteFootprintPoint = z.object({
   x: z.number(),
@@ -324,3 +598,151 @@ export const PluginProgramSiteContextResult =
 export type PluginProgramSiteContextResult = z.infer<
   typeof PluginProgramSiteContextResult
 >
+
+/**
+ * The project's geographic location (WGS84).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `latitude` | `number` | Latitude (degrees) |
+ * | `longitude` | `number` | Longitude (degrees) |
+ */
+export const PluginProgramSiteLocation = z.object({
+  latitude: z.number(),
+  longitude: z.number(),
+})
+export type PluginProgramSiteLocation = z.infer<
+  typeof PluginProgramSiteLocation
+>
+
+/**
+ * Result of {@linkcode PluginProgramSiteApi.getLocation} — the location, or
+ * `null` when the project is not geo-located.
+ */
+export const PluginProgramSiteLocationResult =
+  PluginProgramSiteLocation.nullable()
+export type PluginProgramSiteLocationResult = z.infer<
+  typeof PluginProgramSiteLocationResult
+>
+
+/**
+ * Result of {@linkcode PluginProgramSiteApi.getNorthAngle} — the true-north
+ * angle in degrees (`[0, 360)`, clockwise-positive), or `null` when the
+ * project is not geo-located.
+ */
+export const PluginProgramSiteNorthAngleResult = z.number().nullable()
+export type PluginProgramSiteNorthAngleResult = z.infer<
+  typeof PluginProgramSiteNorthAngleResult
+>
+
+/**
+ * Result of {@linkcode PluginProgramSiteApi.getTimezone} — the IANA timezone
+ * id of the project's geo-location (e.g. `"Europe/London"`), or `null` when
+ * the project is not geo-located.
+ */
+export const PluginProgramSiteTimezoneResult = z.string().nullable()
+export type PluginProgramSiteTimezoneResult = z.infer<
+  typeof PluginProgramSiteTimezoneResult
+>
+
+/**
+ * A summary of the weather file resolved for the project site. Matches the
+ * relevant fields of `analysis.weather`'s `PluginWeatherSourceMeta`;
+ * `selectionMethod` is one of `"nearest-station"`, `"user-upload"`, or
+ * `"project-override"`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `weatherFileId` | `string` | Catalog id (same key as `core.io.import.epw`) |
+ * | `station` | `string` | Station/file name |
+ * | `checksum` | `string` | sha256 of the EPW file |
+ * | `selectionMethod` | `"nearest-station" \| "user-upload" \| "project-override"` | How the file was matched |
+ */
+export const PluginProgramSiteWeather = z.object({
+  weatherFileId: z.string(),
+  station: z.string(),
+  checksum: z.string(),
+  selectionMethod: z.enum([
+    "nearest-station",
+    "user-upload",
+    "project-override",
+  ]),
+})
+export type PluginProgramSiteWeather = z.infer<typeof PluginProgramSiteWeather>
+
+/**
+ * Result of {@linkcode PluginProgramSiteApi.getWeather} — the resolved weather
+ * file summary, or `null` when the project has no geo-located site.
+ */
+export const PluginProgramSiteWeatherResult =
+  PluginProgramSiteWeather.nullable()
+export type PluginProgramSiteWeatherResult = z.infer<
+  typeof PluginProgramSiteWeatherResult
+>
+
+/**
+ * Front / side / rear classification of one site-boundary edge. `"street"`
+ * never appears — the backend synonym resolves to `front`.
+ */
+export const PluginProgramSiteEdgeRole = z.enum(["front", "side", "rear"])
+export type PluginProgramSiteEdgeRole = z.infer<
+  typeof PluginProgramSiteEdgeRole
+>
+
+/**
+ * One boundary edge of a site parcel, as {@linkcode PluginProgramSiteApi.listEdges}
+ * returns it. Coordinates and lengths are world meters.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `edgeIndex` | `number` | Index in the canonicalized (sanitized, CCW) boundary — the same index space the envelope's `edgeOverrides` use |
+ * | `start` / `end` | `{ x, z }` | Edge endpoints, world XZ meters |
+ * | `lengthMeters` | `number` | Edge length in meters |
+ * | `role` | `"front" \| "side" \| "rear"` | Resolved classification (user override wins over the heuristic) |
+ * | `roleSource` | `"override" \| "heuristic"` | Whether the user reassigned this edge's role or the tangent heuristic classified it |
+ * | `setbackMeters` | `number \| null` | Effective base setback (per-edge exception ?? role value); `null` when the parcel has no zoning envelope |
+ */
+export const PluginProgramSiteEdge = z.object({
+  edgeIndex: z.number().int().nonnegative(),
+  start: z.object({ x: z.number(), z: z.number() }),
+  end: z.object({ x: z.number(), z: z.number() }),
+  lengthMeters: z.number(),
+  role: PluginProgramSiteEdgeRole,
+  roleSource: z.enum(["override", "heuristic"]),
+  setbackMeters: z.number().nullable(),
+})
+export type PluginProgramSiteEdge = z.infer<typeof PluginProgramSiteEdge>
+
+/**
+ * Per-parcel entry of {@linkcode PluginProgramSiteApi.listEdges}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `siteId` | `string` | The parcel's component id (same id space as `listPolygons`) |
+ * | `buildableEnvelopeId` | `string \| null` | Linked zoning envelope, when one exists |
+ * | `usingLiveSiteBoundary` | `boolean` | `true` when edges come from the live site boundary; `false` when only the envelope's persisted source polygon was resolvable |
+ * | `staleOverridesDropped` | `boolean` | `true` when persisted edge overrides no longer index-align with the live boundary and were ignored |
+ * | `edges` | `PluginProgramSiteEdge[]` | The classified boundary edges |
+ */
+export const PluginProgramSiteEdgesEntry = z.object({
+  siteId: z.string(),
+  buildableEnvelopeId: z.string().nullable(),
+  usingLiveSiteBoundary: z.boolean(),
+  staleOverridesDropped: z.boolean(),
+  edges: z.array(PluginProgramSiteEdge),
+})
+export type PluginProgramSiteEdgesEntry = z.infer<
+  typeof PluginProgramSiteEdgesEntry
+>
+
+/**
+ * Result of {@linkcode PluginProgramSiteApi.listEdges} — one entry per site
+ * parcel; empty when the project has no site. `lengthUnit` is always `"m"`.
+ */
+export const PluginProgramSiteListEdgesResult = z.object({
+  lengthUnit: z.literal("m"),
+  sites: z.array(PluginProgramSiteEdgesEntry),
+})
+export type PluginProgramSiteListEdgesResult = z.infer<
+  typeof PluginProgramSiteListEdgesResult
+>