@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

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

@@ -0,0 +1,823 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../types";
+/**
+ * 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 (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 (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.
+ *
+ * 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`.
+ */
+export declare 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`)
+     * ```
+     */
+    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()
+     * ```
+     */
+    abstract getArea(): PluginApiReturn<PluginProgramSiteAreaResult>;
+    /**
+     * 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
+     *   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)
+     * ```
+     */
+    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)
+     * ```
+     */
+    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
+     * world-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 }, ...]
+     * ```
+     */
+    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)
+     * ```
+     */
+    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)
+     * ```
+     */
+    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`)
+     * ```
+     */
+    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}`)
+     * ```
+     */
+    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)
+     * ```
+     */
+    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)
+     * ```
+     */
+    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)
+     * ```
+     */
+    abstract updateSiteAnalysis(rows: PluginSiteAnalysisRow[], options?: PluginSiteAnalysisUpdateOptions): PluginApiReturn<PluginProgramSiteAnalysisUpdateResult>;
+}
+/**
+ * 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 declare const PluginSiteAnalysisRow: z.ZodObject<{
+    category: z.ZodString;
+    description: z.ZodString;
+    quantity: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    unit: z.ZodString;
+}, z.core.$strip>;
+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 declare const PluginSiteAnalysisUpdateOptions: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+    siteLocation: z.ZodOptional<z.ZodObject<{
+        lat: z.ZodNumber;
+        lng: z.ZodNumber;
+    }, z.core.$strip>>;
+    sitePolygon: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>>;
+export type PluginSiteAnalysisUpdateOptions = z.infer<typeof PluginSiteAnalysisUpdateOptions>;
+/** Persisted Site Analysis data for the active proposal. */
+export declare const PluginProgramSiteAnalysisResult: z.ZodNullable<z.ZodObject<{
+    sheetName: z.ZodString;
+    siteLocation: z.ZodNullable<z.ZodObject<{
+        lat: z.ZodNumber;
+        lng: z.ZodNumber;
+    }, z.core.$strip>>;
+    sitePolygon: z.ZodNullable<z.ZodString>;
+    rows: z.ZodArray<z.ZodObject<{
+        category: z.ZodString;
+        description: z.ZodString;
+        quantity: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        unit: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+export type PluginProgramSiteAnalysisResult = z.infer<typeof PluginProgramSiteAnalysisResult>;
+/** Result of a merge/append Site Analysis write. */
+export declare const PluginProgramSiteAnalysisUpdateResult: z.ZodObject<{
+    sheetName: z.ZodString;
+    rowCount: z.ZodNumber;
+    updatedRows: z.ZodNumber;
+    appendedRows: z.ZodNumber;
+}, z.core.$strip>;
+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 (world, Snaptrude units) |
+ * | `z` | `number` | Z coordinate (world, Snaptrude units) |
+ */
+export declare const PluginSiteFootprintPoint: z.ZodObject<{
+    x: z.ZodNumber;
+    z: z.ZodNumber;
+}, z.core.$strip>;
+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 declare const PluginSiteGeoPoint: z.ZodObject<{
+    lat: z.ZodNumber;
+    lng: z.ZodNumber;
+    alt: z.ZodNumber;
+}, z.core.$strip>;
+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 declare const PluginSitePolygon: z.ZodObject<{
+    id: z.ZodString;
+    area: z.ZodNumber;
+    label: z.ZodString;
+    footprint: z.ZodArray<z.ZodObject<{
+        x: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+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 declare const PluginProgramSiteSnapshot: z.ZodObject<{
+    units: z.ZodEnum<{
+        ft2: "ft2";
+        m2: "m2";
+    }>;
+    totalArea: z.ZodNumber;
+    polygonCount: z.ZodNumber;
+    polygons: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        area: z.ZodNumber;
+        label: z.ZodString;
+        footprint: z.ZodArray<z.ZodObject<{
+            x: z.ZodNumber;
+            z: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+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 declare const PluginProgramSiteAreaResult: z.ZodObject<{
+    units: z.ZodEnum<{
+        ft2: "ft2";
+        m2: "m2";
+    }>;
+    area: z.ZodNumber;
+}, z.core.$strip>;
+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 declare const PluginProgramSiteListPolygonsResult: z.ZodObject<{
+    units: z.ZodEnum<{
+        ft2: "ft2";
+        m2: "m2";
+    }>;
+    polygons: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        area: z.ZodNumber;
+        label: z.ZodString;
+        footprint: z.ZodArray<z.ZodObject<{
+            x: z.ZodNumber;
+            z: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+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 declare const PluginProgramSiteListGeoPolygonsResult: z.ZodObject<{
+    polygons: z.ZodArray<z.ZodArray<z.ZodObject<{
+        lat: z.ZodNumber;
+        lng: z.ZodNumber;
+        alt: z.ZodNumber;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+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 declare const PluginSiteLatLng: z.ZodObject<{
+    lat: z.ZodNumber;
+    lng: z.ZodNumber;
+}, z.core.$strip>;
+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 declare const PluginSiteBounds: z.ZodObject<{
+    north: z.ZodNumber;
+    south: z.ZodNumber;
+    east: z.ZodNumber;
+    west: z.ZodNumber;
+}, z.core.$strip>;
+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 declare const PluginSiteContextParcel: z.ZodObject<{
+    footprint: z.ZodArray<z.ZodObject<{
+        lat: z.ZodNumber;
+        lng: z.ZodNumber;
+    }, z.core.$strip>>;
+    area: z.ZodNumber;
+}, z.core.$strip>;
+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 declare const PluginProgramSiteContext: z.ZodObject<{
+    center: z.ZodObject<{
+        lat: z.ZodNumber;
+        lng: z.ZodNumber;
+    }, z.core.$strip>;
+    bounds: z.ZodObject<{
+        north: z.ZodNumber;
+        south: z.ZodNumber;
+        east: z.ZodNumber;
+        west: z.ZodNumber;
+    }, z.core.$strip>;
+    widthInM: z.ZodNumber;
+    heightInM: z.ZodNumber;
+    zoom: z.ZodNumber;
+    parcels: z.ZodArray<z.ZodObject<{
+        footprint: z.ZodArray<z.ZodObject<{
+            lat: z.ZodNumber;
+            lng: z.ZodNumber;
+        }, z.core.$strip>>;
+        area: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+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 declare const PluginProgramSiteContextResult: z.ZodNullable<z.ZodObject<{
+    center: z.ZodObject<{
+        lat: z.ZodNumber;
+        lng: z.ZodNumber;
+    }, z.core.$strip>;
+    bounds: z.ZodObject<{
+        north: z.ZodNumber;
+        south: z.ZodNumber;
+        east: z.ZodNumber;
+        west: z.ZodNumber;
+    }, z.core.$strip>;
+    widthInM: z.ZodNumber;
+    heightInM: z.ZodNumber;
+    zoom: z.ZodNumber;
+    parcels: z.ZodArray<z.ZodObject<{
+        footprint: z.ZodArray<z.ZodObject<{
+            lat: z.ZodNumber;
+            lng: z.ZodNumber;
+        }, z.core.$strip>>;
+        area: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+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 declare const PluginProgramSiteLocation: z.ZodObject<{
+    latitude: z.ZodNumber;
+    longitude: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginProgramSiteLocation = z.infer<typeof PluginProgramSiteLocation>;
+/**
+ * Result of {@linkcode PluginProgramSiteApi.getLocation} — the location, or
+ * `null` when the project is not geo-located.
+ */
+export declare const PluginProgramSiteLocationResult: z.ZodNullable<z.ZodObject<{
+    latitude: z.ZodNumber;
+    longitude: z.ZodNumber;
+}, z.core.$strip>>;
+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 declare const PluginProgramSiteNorthAngleResult: z.ZodNullable<z.ZodNumber>;
+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 declare const PluginProgramSiteTimezoneResult: z.ZodNullable<z.ZodString>;
+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 declare const PluginProgramSiteWeather: z.ZodObject<{
+    weatherFileId: z.ZodString;
+    station: z.ZodString;
+    checksum: z.ZodString;
+    selectionMethod: z.ZodEnum<{
+        "nearest-station": "nearest-station";
+        "user-upload": "user-upload";
+        "project-override": "project-override";
+    }>;
+}, z.core.$strip>;
+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 declare const PluginProgramSiteWeatherResult: z.ZodNullable<z.ZodObject<{
+    weatherFileId: z.ZodString;
+    station: z.ZodString;
+    checksum: z.ZodString;
+    selectionMethod: z.ZodEnum<{
+        "nearest-station": "nearest-station";
+        "user-upload": "user-upload";
+        "project-override": "project-override";
+    }>;
+}, z.core.$strip>>;
+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 declare const PluginProgramSiteEdgeRole: z.ZodEnum<{
+    front: "front";
+    side: "side";
+    rear: "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 declare const PluginProgramSiteEdge: z.ZodObject<{
+    edgeIndex: z.ZodNumber;
+    start: z.ZodObject<{
+        x: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strip>;
+    end: z.ZodObject<{
+        x: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strip>;
+    lengthMeters: z.ZodNumber;
+    role: z.ZodEnum<{
+        front: "front";
+        side: "side";
+        rear: "rear";
+    }>;
+    roleSource: z.ZodEnum<{
+        override: "override";
+        heuristic: "heuristic";
+    }>;
+    setbackMeters: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+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 declare const PluginProgramSiteEdgesEntry: z.ZodObject<{
+    siteId: z.ZodString;
+    buildableEnvelopeId: z.ZodNullable<z.ZodString>;
+    usingLiveSiteBoundary: z.ZodBoolean;
+    staleOverridesDropped: z.ZodBoolean;
+    edges: z.ZodArray<z.ZodObject<{
+        edgeIndex: z.ZodNumber;
+        start: z.ZodObject<{
+            x: z.ZodNumber;
+            z: z.ZodNumber;
+        }, z.core.$strip>;
+        end: z.ZodObject<{
+            x: z.ZodNumber;
+            z: z.ZodNumber;
+        }, z.core.$strip>;
+        lengthMeters: z.ZodNumber;
+        role: z.ZodEnum<{
+            front: "front";
+            side: "side";
+            rear: "rear";
+        }>;
+        roleSource: z.ZodEnum<{
+            override: "override";
+            heuristic: "heuristic";
+        }>;
+        setbackMeters: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+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 declare const PluginProgramSiteListEdgesResult: z.ZodObject<{
+    lengthUnit: z.ZodLiteral<"m">;
+    sites: z.ZodArray<z.ZodObject<{
+        siteId: z.ZodString;
+        buildableEnvelopeId: z.ZodNullable<z.ZodString>;
+        usingLiveSiteBoundary: z.ZodBoolean;
+        staleOverridesDropped: z.ZodBoolean;
+        edges: z.ZodArray<z.ZodObject<{
+            edgeIndex: z.ZodNumber;
+            start: z.ZodObject<{
+                x: z.ZodNumber;
+                z: z.ZodNumber;
+            }, z.core.$strip>;
+            end: z.ZodObject<{
+                x: z.ZodNumber;
+                z: z.ZodNumber;
+            }, z.core.$strip>;
+            lengthMeters: z.ZodNumber;
+            role: z.ZodEnum<{
+                front: "front";
+                side: "side";
+                rear: "rear";
+            }>;
+            roleSource: z.ZodEnum<{
+                override: "override";
+                heuristic: "heuristic";
+            }>;
+            setbackMeters: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginProgramSiteListEdgesResult = z.infer<typeof PluginProgramSiteListEdgesResult>;
+//# sourceMappingURL=site.d.ts.map